How to insert and update for each major entity.
Overview
Post tasks to the following URL
https://[WSUrl]/tasks?wsccesskey=[WSAccessKey]&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.
insertContact and updateContact
Summary
Inserts / updates Contact.
| Field | Type | Max. Length | Required? | Notes |
|---|---|---|---|---|
| contact | Contact | Y | The Contact to be inserted / updated. |
Example: Insert Contact
Request content:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<insertContact>
<contact uid=”0″>
<salutation>Mr.</salutation>
<givenName>John</givenName>
<familyName>Smith</familyName>
<organisationName>ACME Pty Ltd</organisationName>
<organsiationAbn>11 111 111 111</organisationAbn>
<organisationWebsite>www.acm.com</organisationWebsite>
<organisationPosition>Director</organisationPosition>
<abn>67 093 453 886</abn>
<email>john.smith@acme.com.au</email>
<mainPhone>02 9999 9999</mainPhone>
<homePhone>02 8888 8888</homePhone>
<mobilePhone>0444 444 444</mobilePhone>
<contactID>101</contactID>
<tags>Prospect, IT</tags>
<postalAddress>
<street>3/33 Victory Av</street>
<city>North Sydney</city>
<state>NSW</state>
<postCode>2112</postCode>
<country>Australia</country>
</postalAddress>
<otherAddress>
<street>12/22</street>
<city>Pennant Hills</city>
<state>NSW</state>
<postCode>2122</postCode>
<country>Australia</country>
</otherAddress>
<isActive>true</isActive>
</contact>
</insertContact>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<insertContactResult insertedEntityUid=”22729″ lastUpdatedUid=”AAAAAAAVA7s=” />
</tasksResponse>
Example: Update Contact
https://[WSUrl]/tasks?wsccesskey=[WSAccessKey]&fileuid=[FileUid]
Request content:
<?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. & Mrs. Smith</organisationName>
<organisationAbn />
<organisationWebsite />
<organisationPosition>Director</organisationPosition>
<abn>67 093 453 886</abn>
<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:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateContactResult updatedEntityUid=”22730″ lastUpdatedUid=”AAAAAAAVA8E=” />
</tasksResponse>
insertTransactionCategory and updateTransactionCategory
Summary
Inserts / updates Account
| Field | Type | Max. Length | Required? | Notes |
|---|---|---|---|---|
| transactionCategory | TransactionCategory | Y | The TransactionCategory to be inserted / updated. |
Example: Insert Account
Request content:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<insertTransactionCategory>
<transactionCategory uid=”0″>
<type>Income</type>
<name>Consulting Fees</name>
<isActive>true</isActive>
</transactionCategory>
</insertTransactionCategory>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<insertTransactionCategoryResult insertedEntityUid=”10521″ lastUpdatedUid=”AAAAAAAVA8g=” />
</tasksResponse>
Example: Update Account
Request content:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<insertTransactionCategory>
<transactionCategory uid=”0″>
<type>Income</type>
<name>6a91110607244ef - For Testing Update</name>
<isActive>true</isActive>
</transactionCategory>
</insertTransactionCategory>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateTransactionCategoryResult updatedEntityUid=”10522″ lastUpdatedUid=”AAAAAAAVA8o=” />
</tasksResponse>
insertBankAccount and updateBankAccount
Summary
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:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<insertBankAccount>
<bankAccount uid=”0″>
<type>Asset</type>
<name>CBA</name>
<isActive>true</isActive>
<displayName>CBA</displayName>
<bsb>111-111</bsb>
<accountNumber>12345-6789</accountNumber>
</bankAccount>
</insertBankAccount>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<insertBankAccountResult insertedEntityUid=”10523″ lastUpdatedUid=”AAAAAAAVA8s=” />
</tasksResponse>
Example: Update Bank Account
NOTE: The displayName element is required.
Request content:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<updateBankAccount>
<bankAccount uid=”10524″ lastUpdatedUid=”AAAAAAAVA8w=”>
<type>Loan</type>
<name>CBA</name>
<isActive>true</isActive>
<displayName>CBA 12345</displayName>
<bsb>111-111</bsb>
<accountNumber>12345-6789</accountNumber>
</bankAccount>
</updateBankAccount>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateBankAccountResult updatedEntityUid=”10524″ lastUpdatedUid=”AAAAAAAVA80=” />
</tasksResponse>
insertInventoryItem and updateInventoryItem
Summary
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:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<insertInventoryItem>
<inventoryItem uid=”0″>
<code>CODE_e8f-4af6-8b34-dfa1bfd18550</code>
<description>Description for CODE_e8f-4af6-8b34-dfa1bfd18550</description>
<isActive>true</isActive>
<notes>Notes for CODE_e8f-4af6-8b34-dfa1bfd18550</notes>
<isInventoried>true</isInventoried>
<assetAccountUid>10525</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</saleTaxCode>
<saleCoSAccountUid>10527</saleCoSAccountUid>
<rrpInclTax>19.95</rrpInclTax>
</inventoryItem>
</insertInventoryItem>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<insertInventoryItemResult insertedEntityUid=”2047″ lastUpdatedUid=”ece9a802-0611-4a7a-8aad-30eaf8e09a39″ />
</tasksResponse>
Example: Update Inventory Item
Request content:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasks>
<updateInventoryItem>
<inventoryItem uid=”2047″ lastUpdatedUid=”ece9a802-0611-4a7a-8aad-30eaf8e09a39″>
<code>CODE_e8f-4af6-8b34-dfa1bfd18550</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>
<rrpInclTax>19.95</rrpInclTax>
</inventoryItem>
</updateInventoryItem>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateInventoryItemResult updatedEntityUid=”2047″ lastUpdatedUid=”328b1df2-5cd0-47e4-8702-773e27259fb4″ />
</tasksResponse>
insertInvoice and updateInvoice
Summary
Inserts / updates Invoice. You can also ask the system to email PDF invoice at the same time.
| Field | Type | Max. Length | Required? | Notes |
|---|---|---|---|---|
| emailToContact | Boolean | Specifies whether to email the PDF invoice. Default: false (don’t email to contact). | ||
| invoice | Invoice | Y | The Invoice to be inserted / updated. | |
| createAsAdjustmentNote | Boolean | Specifies whether to create the PDF invoice to be emailed to contact as an adjustment note. Default: false. | ||
| 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 “ |
| generatedPurchaseOrderNumber | String | When inserting a purchase and the purchase order number is set to “ |
Example: Insert Service Sale & Email to Contact
Request content:
<?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>
<folderUid>0</folderUid>
<summary>Test POST sale</summary>
<notes>From REST</notes>
<requiresFollowUp>false</requiresFollowUp>
<dueOrExpiryDate>2005-12-01</dueOrExpiryDate>
<layout>S</layout>
<status>I</status>
<invoiceNumber><Auto Number></invoiceNumber>
<purchaseOrderNumber>PO222</purchaseOrderNumber>
<invoiceItems>
<serviceInvoiceItem>
<description>Design & 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>
<createAsAdjustmentNote>false</createAsAdjustmentNote>
<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:
<tasksResponse>
<insertInvoiceResult insertedEntityUid=”256872″ lastUpdatedUid=”AAAAAAAVBA4=” sentToContact=”true” generatedInvoiceNumber=”XYZ-2341″/>
</tasksResponse>
Example: Update Service Sale
Request content:
<?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>
<tags>Online Sales</tags>
<summary>Service Sale 2</summary>
<requiresFollowUp>false</requiresFollowUp>
<dueOrExpiryDate>2005-12-15</dueOrExpiryDate>
<layout>S</layout>
<status>I</status>
<invoiceNumber><Auto Number></invoiceNumber>
<purchaseOrderNumber>PO123456789</purchaseOrderNumber>
<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>
<createAsAdjustmentNote>false</createAsAdjustmentNote>
</updateInvoice>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateInvoiceResult updatedEntityUid=”256875″ lastUpdatedUid=”AAAAAAAVBCw=” sentToContact=”false” />
</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:
<?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>
<invoicePaymentItems>
<invoicePaymentItem>
<invoiceUid>256878</invoiceUid>
<amount>20.05</amount>
</invoicePaymentItem>
<invoicePaymentItem>
<invoiceUid>256877</invoiceUid>
<amount>23.75</amount>
</invoicePaymentItem>
</invoicePaymentItems>
</invoicePayment>
</insertInvoicePayment>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<insertInvoicePaymentResult insertedEntityUid=”256879″ lastUpdatedUid=”AAAAAAAVBEg=” />
</tasksResponse>
Example: Update Invoice Payment for Sales
Request content:
<?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>
<invoicePaymentItems>
<invoicePaymentItem>
<invoiceUid>256881</invoiceUid>
<amount>30</amount>
</invoicePaymentItem>
</invoicePaymentItems>
</invoicePayment>
</updateInvoicePayment>
</tasks>
Response:
<?xml version=”1.0″ encoding=”utf-8″?>
<tasksResponse>
<updateInvoicePaymentResult updatedEntityUid=”256883″ lastUpdatedUid=”AAAAAAAVBGY=” />
</tasksResponse>
