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 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.
This table lists throttling rates on a per-hour basis unless otherwise noted. The context of "Organization ID" in this table depends on the context of the method. For example, Organization ID can refer to a customer account or the buyer/seller (if buyers or sellers are in use).
|Method||Maximum requests per hour||Throttled by|
|IsAuthenticated||1,000||Organization ID and Current user|
|SignOut||1,000||Organization ID and Current user|
|Touch||1,000||Organization ID and Current user|
|Customer master data|
|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||2,000||Customer ID and Current user|
|SearchMasterDataObjects||2,000||Organization ID and Current user|
|GetMasterDataObjectsMatchingSearchValue||2,000||Organization ID, Master data object type and Current user|
|Purchase order master data|
|SearchPurchaseOrderFilteredLines||400||Organization ID and Current user|
|SearchPurchaseOrders||400||Organization ID and Current user|
|Supplier master data|
|SearchSuppliers||60||Customer ID and Current user|
|SearchSuppliersQuery||400||Organization ID and Current user|
|SearchSuppliersWithQueryResult||600||Customer ID and Current user|