API access requirements

To keep API integrations running smoothly, there are a number of key concepts you must adhere to. Failure to follow any these requirements can result in errors and reduced performance.

  • The API is not intended to provide a live feed of the data inside of AP Essentials. For example, retrieving all records every few seconds to provide an up-to-date view in another system is not a supported scenario.
  • Authentication tokens are saved in a cookie and expire after 30 minutes of inactivity. Therefore, your integration does not need to re-authenticate for every API operation. You only need to authenticate if your integration has not made a request for over 30 minutes.

  • If you need to retrieve a lot of records, retrieve 2000 - 5000 records at a time. Do not retrieve one record at a time.
  • Perform master-data synchronization on a schedule, such as four times per day or once per hour. Do not perform master-data synchronization in an infinite loop.
  • When synchronizing data with an external system, only synchronize changed data. Do not synchronize all data at once. For example, if supplier master data is synchronized and the external system uses timestamps, only update records whose timestamp has been updated since the last synchronization.
  • Do not synchronize documents to be exported or posted more than once every 2 minutes.
  • Note the limits on max number of entities allowed. Exceeding these limits will cause errors.
  • Note that requests may be throttled. If a request is throttled, HTTP error code 429 is returned.

API throttling

API throttling is the process of limiting the number of API requests you can make during a certain period. AP Essentials throttles key API methods to promote stability and fair usage of the system. If a request is throttled, HTTP error code 429 is returned.

Throttling rates

This table lists throttling rates on a per-hour basis unless otherwise noted.

Method Maximum requests per hour Throttled by
Customer master data
DeleteMasterDataCustomers 10 Organization ID
AddOrUpdateMasterDataCustomers 10 Organization ID
DeleteMasterDataCustomersById 500 Organization ID
AddOrUpdateSingleMasterDataCustomer 100 Organization ID and Current user
SearchMasterDataCustomers 500 Organization ID and Current user
StartMasterDataCustomerUpload 1 request every 2 hours Organization ID
CompleteMasterDataCustomerUpload 1 request every 1 hour 55 minutes Organization ID
Generic master data objects
SetMasterDataObjects 60 Organization ID and Master data object type
AddOrUpdateMasterDataObjects 60 Organization ID and Master data object type
DeleteMasterDataObjects 60 Organization ID and Master data object type (a collection of object types can be specified )
GetMasterDataObjects 300 Organization ID and Master data object type
GetAvailableMasterDataObjectTypesByCustomerId 2000 Customer ID and Current user
SearchMasterDataObjects 2000 Organization ID and Current user
GetMasterDataObjectsMatchingSearchValue 2000 Organization ID, Master data object type and Current user
Purchase order master data
SetPurchaseOrders 60 Organization ID
AddOrUpdatePurchaseOrders 120 Organization ID
DeletePurchaseOrders 120 Organization ID
GetPurchaseOrders 100 Organization ID
SearchPurchaseOrderFilteredLines 400 Organization ID and Current user
SearchPurchaseOrders 400 Organization ID and Current user
Supplier master data
SetSuppliers 100 Organization ID
AddOrUpdateSuppliers 400 Organization ID
AddOrUpdateSupplierWithBankAccounts 400 Organization ID
DeleteSuppliersById 100 Organization ID
DeleteSuppliers 200 Organization ID
GetSuppliers 200 Organization ID
GetSupplier 100 Organization ID
SearchSuppliers 60 Customer ID and Current user
SearchSuppliersQuery 400 Organization ID and Current user
SearchSuppliersWithQueryResult 600 Customer ID and Current user