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. 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
Authenticate 1,000 UserName
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
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 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
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

Monitoring API Throttling via HTTP Headers

When you make HTTP requests to an endpoint that supports throttling, AP Essentials provides throttling information in the HTTP header. These headers are returned simultaneously:

  • X-RateLimit-WindowSize — Throttling involves setting a limit on the number of requests allowed within a designated time frame, such as one hour. The X-RateLimit-WindowSize header denotes the duration of this window in seconds.

  • X-RateLimit-Reset — This header shows how many seconds are left until the end of the current throttling window.

  • X-RateLimit-Limit — This header shows how many requests can be performed within the throttling window.

  • X-RateLimit-Remaining — This header shows how many requests remain before throttling is applied.

Consider this example:

X-RateLimit-WindowSize: 3600
X-RateLimit-Reset: 3300
X-RateLimit-Limit: 400
X-RateLimit-Remaining: 397

These headers indicate a time window of 3,600 seconds (1 hour). The window will reset in 3,300 seconds (55 minutes). Within this 3,600-second window, a total of 400 requests are permitted. Currently, you have the capacity to make 397 more requests within the remaining 3,300 seconds (55 minutes). To clarify, you can make up to 400 requests per hour, and so far, you have made three requests in the first five minutes. If you attempt to exceed the limit of 400 requests within the one-hour period, your requests will be throttled until the time window resets.