With the API you connect your own system directly to POM Collect: create collection orders, pass on payments and deliver documents, fully automatically. Request access from POM, build your integration in the test environment and then go live. The technical details per endpoint are in the API documentation.
How to start
- Request access to the API from POM. You receive a client ID and a client secret, separately for your test environment and your production environment.
- Use your client ID and client secret to request a token at
POST /oauth/token. A token is valid for one hour; after that you request a new one. - Send the token with every call, as a Bearer token in the
Authorizationheader. - Build and test your integration in the test environment. Only then move it to production.
If you still use API v2, you can use API v3 alongside it. You do not have to rebuild everything at once; new features are only added to API v3.
The limit on the number of calls
Each environment has a budget of 5000 points per minute, for all endpoints together. Most calls cost 1 point.
| Call | Points |
|---|---|
| A regular call, such as creating a collection order or passing on a payment | 1 |
| Delivering a document, on its own or together with a collection order | 40 |
| Every call in the test environment | 10 times as much (separate budget) |
With documents you can therefore process up to 125 per minute. When your budget runs out, you get status 429 and the X-RateLimit-Retry-After header tells you after how many seconds you can continue. Every response shows in X-RateLimit-Remaining how many points you have left.
Why documents cost more points
The portal processes each document immediately, within the same call: checking, storing and making it visible to your customer. Only then do you get a response. So you know straight away whether the document was accepted and do not have to check afterwards whether everything went well. That takes more computing power than a regular call.
The limit is deliberately conservative. This way a large batch always takes the same time, even when other organisations deliver at the same moment. A batch of 60,000 documents takes about eight hours. Schedule such a batch at night or outside office hours.
Good to know
- The API documentation is public. You can send the link to your IT partner.
- Store the
collection_order_idfrom the response. You use it to address the collection order directly later. - Build a retry into your integration after a 429, using the waiting time from the header.