Skip to main content
Skip table of contents

Integrating customer data with REST API

This page is for MYOB partners familiar with APIs.

When integrating customer data into MYOB Acumatica — Payroll, there are two endpoints on the Web Service Endpoints screen that you can use for integrating data with REST API:

  • ADVPAU is the endpoint for the Australian version of payroll.

  • ADVPNZ is the endpoint for the New Zealand version of payroll.

Both endpoints are based on the 20.200.001 endpoint version of the MYOB Acumatica platform.

The ADVP endpoints cover the following entities related to payroll:

  • Employee – organisational employee record with payroll-specific information: Employment History, Payroll Expense Allocation Settings.

  • PayDetails – Payroll Employee, Employee and Taxation Settings, Pay Distribution, Employee Pay Groups and Standard Pay.

  • PayItem – Pay Items.

  • Entitlement – Entitlements.

  • PostingClass – Payroll Posting Classes.

  • GLPurpose – General Ledger Purposes.

  • PayItemLiabilities – Pay Item Liabilities.

  • Timesheet – Import Timesheet batches.

  • DataMap – mapping rules for the Timesheet Import.

The ADVP endpoints also cover some entities shared with fields related to payroll – like Employees.

Because the ADVP endpoints are not based on any other endpoints, you might need to use a different endpoint if you need access to entities that aren't covered by the ADVP endpoints. For example, if a third-party software needs to access the list of GL Accounts, you can use the Default endpoint.

REST API examples that use the ADVP endpoints

Below, you can find examples of HTTP requests for supported business scenarios in MYOB Acumatica — Payroll. These requests might not meet your exact requirements, so you might need to tweak them to import or retrieve the data you need.

In the examples below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance. For example, https://mycompany.myobacumatica.com.

Creating an employee

The following HTTP request is an example of how to create an employee. In this example, the employee's ID is EMP000111.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/Employee?$expand=EmployeeSettings,FinancialSettings,MainAddress,MainContact,EmploymentHistory,ExpenseAllocationSettings

Body

{
    "EmployeeID": {"value": "EMP000111"},

    "Status": {"value": "Active"},

 
    "EmployeeSettings":
    {
        "EmployeeClass": {"value": "EMPLYDFT"},
        "BranchID": {"value": "MAIN"},
        "Calendar": {"value": "AUCALENDAR"},
        "CurrencyID": {"value": "AUD"},
        "CurrencyRateTypeID": {"value": "SPOT"},
        "DepartmentID": {"value": "ADMIN"},
        "EmployeeRefNbr": {"value": "EXTREF001"},
        "EnableCurrencyOverride": {"value": true},
        "EnableRateOverride": {"value": true},
        "LaborItem": {"value": "TCIMPORT"},
        "RegularHoursValidation": {"value": "Warning Only"},
        "ReportsTo": {},
        "RouteEmails": {"value": true},
        "Salesperson": {},
        "TimeCardIsRequired": {"value": false}
    },

    "EmploymentHistory": [
    {
            "LineNbr": {"value": 1},
            "Active": {"value": true},
            "ApprenticeTrainee": {"value": false},
            "EmploymentBasis": {"value": "Full-time"},
            "EmploymentStatus": {"value": "Permanent"},
            "StartDate": {"value": "2014-10-10T00:00:00+11:00"},
            "EndDate": {},
            "Position": {"value": "SUPENG"},
            "RehireEligible": {"value": false},
            "ServiceBreak": {"value": false},
            "StartReason": {"value": "New Hire"},
            "Terminated": {"value": false},
            "TerminationReason": {}
    }
    ],
   
    "FinancialSettings":
    {
                "APAccount": {},
        "APSubaccount": {},
        "CashAccount": {"value": "AUCASHACC"},
        "ExpenseAccount": {"value": "50"},
        "ExpenseSubaccount": {"value": "0"},
        "PaymentMethod": {"value": "AUANZDC"},
        "PrepaymentAccount": {},
        "PrepaymentSubaccount": {},
        "SalesAccount": {"value": "40"},
        "SalesSubaccount": {"value": "0"},
        "TaxZone": {"value": "DOMESTIC"},
        "Terms": {"value": "CASHONLY"}
    },

   
    "MainAddress":
    {
        "AddressLine1": {"value": "Number 30"},
        "AddressLine2": {"value": "This and That Street"},
        "City": {"value": "Melbourne"},
        "Country": {"value": "AU"},
        "PostalCode": {"value": "0493"},
        "State": {"value": "VIC"}
    },

    "MainContact":
    {
        "DateOfBirth": {"value": "1980-02-09T00:00:00+11:00"},
        "Email": {"value": "EmilyB@myobap.com"},
        "Fax": {"value": "032433433"},
        "FaxType": {"value": "Home Fax"},
        "FirstName": {"value": "First Name"},
        "Gender": {"value": "Female"},
        "LastName": {"value": "Test Last"},
        "MaritalStatus": {"value": "Married"},
        "MiddleName": {"value": "Test Middle"},
        "Phone1": {"value": "034928393"},
        "Phone1Type": {"value": "Home"},
        "Phone2": {"value": "3489783429"},
        "Phone2Type": {"value": "Cell"},
        "Phone3": {"value": "045454355"},
        "Phone3Type": {"value": "Business 1"},
        "SpousePartnerName": {"value": "John"},
        "Title": {"value": "Miss"},
        "Web": {}
    },

    "ExpenseAllocationSettings":
    {
                "AllocationMethod": {"value": "Time"}
    },
}

Having the $expand or $select parameters return the required details of the request examples below, <MYOB Acumatica instance URL> is the URL of the MYOB Acumatica instance (such as https://mycompany.myobacumatica.com).

Retrieving information about an employee

There are two ways to retrieve information about an employee.

If you know the employee's ID

Method

Host

GET

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/Employee/ EMP000111?$expand=EmployeeSettings,FinancialSettings,MainAddress,MainContact,EmploymentHistory,ExpenseAllocationSettings

If you don't know the employee's ID

You can use the $filter parameter with the External Reference Number field of the employee. In the example below, this is EXTREF001.

Method

Host

GET

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/Employee?$expand=EmployeeSettings,FinancialSettings,MainAddress,MainContact,EmploymentHistory,ExpenseAllocationSettings&$filter= EmployeeSettings/EmployeeRefNbr eq 'EXTREF001'

Creating a pay item

The following HTTP request is an example of how to create a pay item. In this example, the pay item is called ESSWAGES.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayItem

Body

{
  "PayItemID": {"value": "ESSWAGES"},
  "Description": {"value": "ESS Ordinary Wages"},
  "EntitlementID": {},
  "Paysliplabel": {"value": "ESS Ordinary Wages"},
  "Type": {"value": "INCOME"},
   "AdditionalInfo":
   {
                "AllowPartialDeduction": {"value": false},
     "CashAccount": {},
     "CurrentPay": {"value": true},
     "DeductionCategory": {},
     "ExcludefromAllocation": {},
     "GeneralLedgerPurpose": {"value": "GLP000001"},
     "IncludeAccrualinGL": {},
     "Overridelegislatedrates": {},
     "PaymentMethod": {},
     "ProtectedEarnings": {},
     "ProtectedEarningsruleCustomProtectedEarningsRuleCD": {},
     "ReducingBalanceCalculation": {},
     "ShowCalculatedDollarValue": {"value": true}
     "ShowCalculatedUnits": {"value": true},
     "ShowOnPayslip": {"value": true},
     "StandardPay": {"value": true},
     "SupplierID": {},
     "UpdateQuantityforTimeAllocation": {}
    },
   
    "CalculationMethod":
    {
        "AccrualMethod": {},
        "Amount": {},
        "CustomRate": {"value": 0},
        "Defaultnumberofunits": {"value": 38},
        "EmployeeRateCD": {"value": "1"},
        "Excludingthefirst": {},
        "FormRateType": {"value": "Entered"},
        "FormRateValueType": {"value": "Use Employee's Rate"},
        "IsDerivedType": {},
        "Method": {"value": "Rated"},
        "Percentage": {},
        "perExcludeFrequency": {"value": "Pay"},
        "perFrequency": {"value": "Pay"},
        "Precision": {"value": "Rounded Cents"},
        "Ratemultiplier": {"value": 1},
        "UnitType": {"value": "Hours"},
        "whichrepresents": {}
    },
}

Creating a payroll employee record

The following HTTP request is an example of how to create a payroll employee record for a previously created employee. In this example, the employee's ID is EMP000111.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails

Body

{
                "EmployeeID":{"value":"EMP000111"},
               
                "Taxation": {
        "Residency": {"value": "Australian"},
        "AustralianbusinessnumberABN":{},
        "Claimtaxfreethreshold":{"value":false},
        "IsAUJurisdiction":{"value":true},
        "Contracttype": {"value": "Individual"},
        "Employmentbasis": {"value": "Full-time"},
        "OverridePSType": {"value": false},
        "Paymentsummarytype": {"value": "Not Required"},
        "TaxfilenumberTFN": {"value": ""}
    },
                "PayrollPostingClass": {
        "value": "CLASS1"
    },
    "Code": {
        "value": "CODE1"
    },
       
    "PayDistribution":
{
   "PaymentMethod":{"value":"AUANZDC"},
                   "CashAccount":{"value":"AUCASHACC"},
               
                 "PayDistributionDetails" : [
                {
        "Type":{"value":"Amount"},
                    "BSBNumber":{"value":"222222"},
                    "AccountNumber":{"value":"66165151"},
                    "NameOnAccount":{"value":"Riley Mills Amount"},
                    "FixedAmount":{"value":"10"},
                    "Reference": {"value":"ref a"},
                    "Sequence":{"value":1},
    },
    {
        "Type":{"value":"Balance"},
                    "BSBNumber":{"value":"555555"},
                    "AccountNumber":{"value":"65165152"},
                    "NameOnAccount":{"value":"Riley Mills"},
                    "Reference": {"value":"ref b"},
         "Sequence":{"value":99},
    },
   ],
  },
}

Adding and updating an employee's pay groups

Adding pay groups

The following HTTP request is an example of how to create employee pay groups for a previously created employee. In this example, the employee's ID is EMP000111. You can also incorporate the pay groups section to the initial call for the payroll employee creation.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails?$expand=PayGroups

Body

                {
                "EmployeeID":{"value":"EMP000111"},
                "PayGroups": [
        {
                 "EmployeePayGroupCode": {"value": 1},
                 "PayGroupID": {"value": "ESSMONTHLYPAY"},
            "DefaultPayGroup": {"value": true},
            "AnnualSalary": {"value": 106000},
            "CalendarID": {"value": "AUCALENDAR"},
            "EffectiveDate": {"value": "2015-01-30T00:00:00+11:00"},
            "HoursPerDay": {"value": 7.39},
        },
        {
            "EmployeePayGroupCode": {"value": 2},
                      "PayGroupID": {"value": "ESSPGROUP"},
            "DefaultPayGroup": {"value": false},
            "AnnualSalary": {"value": 106000},
            "CalendarID": {"value": "AUCALENDAR"},
            "EffectiveDate": {"value": "2015-01-01T00:00:00+11:00"},
            "HoursPerDay": {"value": 7.383333},
        },
      ],
}

You don't need to include the EmployeePayGroupCode in the creation request, because the IDs will be automatically generated during creation.

Use $expand=PayGroups to get the EmployeePayGroupCode of the created pay groups (Standard Pay ID) record. It will be required for the updating of the existing Employee PayGroup records.

Updating existing pay groups

The request below is an example of how to update the existing PayGroups, since the automatically generated IDs (300 and 301) have been used in the request.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails?$expand=PayGroups

Body

                {
                "EmployeeID":{"value":"EMP000111"},
                "PayGroups": [
        {
                 "EmployeePayGroupCode": {"value": 300},
            "AnnualSalary": {"value": 107000},
        },
        {
            "EmployeePayGroupCode": {"value": 301},              
            "EffectiveDate": {"value": "2015-07-01T00:00:00+11:00"},
        },
      ],
}

Adding and updating an employee's standard pay

The following HTTP request is an example of how to populate the Employee Standard Pay for a specific Pay Group. In this example, the previously created employee's ID is EMP000111. You need to use the Pay Item internal ID to correctly identify the pay item in the Standard Pay.

To retrieve the internal ID of the Pay Item, add &$custom=PayItem.PayItemID parameter to the GET Pay Item call

Also, use the PayGroupCode (which is the internal ID) to specify which PayGroup is going to be updated.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails?$expand=StandardPay,StandardPay/StandardPayDetails

Body

                {
                "EmployeeID":{"value":" EMP000111"},   
    "StandardPay": {
        "PayDetailsfor": {"value": 300},       
        "StandardPayDetails": [
            {
                "PayItem": {"value": 547},
                 "Quantity": {"value": 42},
                "Supplier": {},
                "Location": {},
                "PaymentMethod": {},
                "CashAccount": {},
                "PaymentReference": {},
                "Code": {},
                "Particulars": {},
                "RecoveredToDate": {},
                "AmountToRecover": {},
                "ReducingBalance": {"value": "No"},
                "FundName": {},
                "MemberID": {},
                "ShowPayItemDetails": {"value": true},
            },               
            {
                "PayItem": {"value": 299},
                "Quantity": {},
                "Supplier": {},
                "Location": {},
                "PaymentMethod": {},
                "CashAccount": {},
                "PaymentReference": {},
                "Code": {},
                "Particulars": {},
                "RecoveredToDate": {},
                "AmountToRecover": {},
                "ReducingBalance": {},
                "FundName": {},
                "MemberID": {},
                "ShowPayItemDetails": {"value": true},
            },
        ]
    }
}

Use the returned StandardPayPayItemID to identify the Standard Pay Pay Item line for the future updates.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails?$expand=StandardPay,StandardPay/StandardPayDetails

Body

                {
                "EmployeeID":{"value":" EMP000111"},   
    "StandardPay": { "PayDetailsfor": {"value": 300},       
    "StandardPayDetails": [
            {
                "StandardPayPayItemID": {"value": 552},
                "PayItem": {"value": 547},
                 "Quantity": {"value": 44},
                "Supplier": {},
                "Location": {},
                "PaymentMethod": {},
                "CashAccount": {},
                "PaymentReference": {},
                "Code": {},
                "Particulars": {},
                "RecoveredToDate": {},
                "AmountToRecover": {},
                "ReducingBalance": {"value": "No"},
                "FundName": {},
                "MemberID": {},
                "ShowPayItemDetails": {"value": true}
                },
               
                {
                "StandardPayPayItemID": {"value": 553},
                "PayItem": {"value": 299},
                "Quantity": {},
                "Supplier": {},
                "Location": {},
                "PaymentMethod": {},
                "CashAccount": {},
                "PaymentReference": {},
                "Code": {},
                "Particulars": {},
                "RecoveredToDate": {},
                "AmountToRecover": {},
                "ReducingBalance": {},
                "FundName": {},
                "MemberID": {},
                "ShowPayItemDetails": {"value": false}
                }
        ]       
    }
}

Retrieving information about the payroll employee and standard pay

Method

Host

GET

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/PayDetails/EMP000111?$expand=PayGroups,StandardPay,StandardPay/StandardPayDetails,PayDistribution,PayDistribution/PayDistributionDetails,Taxation

Adding an employee timesheet

The following HTTP request is an example of how to create an Import Timesheet Batch record. Use the Batchnumber returned in the response to find the created batch in subsequent requests.

Method

Host

PUT

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/Timesheet?$expand=TimesheetDetail

Body

                {
    "Datasourcetype": {"value": "PAYRUNTEST"},
    "TimesheetDetail": [
        {
            "ExtemployeeID": {"value": "EMP0001"},
            "Extemployeename": {"value": "Walsh Ian Warren"},
            "Extpayitemdescription": {},
            "ExtpayitemID": {"value": "PI0033"},
            "Extsubaccount": {"value": "0"},
            "ExtProject": {},
            "ExtProjectTask": {},
            "ExtInventoryItem": {},
            "Timesheetdate": {"value": "2022-01-01T00:00:00+11:00"},
            "Quantity": {"value": 2},
            "Amount": {}
        },
        {
            "ExtemployeeID": {"value": "EMP0001"},
            "Extemployeename": {"value": "Walsh Ian Warren"},
            "Extpayitemdescription": {},
            "ExtpayitemID": {"value": "PI0033"},
            "Extsubaccount": {"value": "0"},
            "ExtProject": {},
            "ExtProjectTask": {},
            "ExtInventoryItem": {},
            "Timesheetdate": {"value": "2022-01-02T00:00:00+11:00"},
            "Quantity": {"value": 8},
            "Amount": {}
        }
    ]
}

Mapping employee timesheet items

The following HTTP request is an example of how to execute the Map Imported Items action against an Import Timesheet Batch record. Use the Batchnumber returned in the previous response.

Method

Host

POST

<MYOBAcumaticaInstanceURL>/entity/ADVPAU/20.200.001/Timesheet/Mapping

Body

{
"entity" :
{
"Batchnumber" : {"value" : "TSB001502"}
}
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.