A lookup that finds nothing is no longer charged
StableA postcode or address lookup that returns no address data now gives its credit back automatically, in line with Royal Mail's Transaction definition. No integration changes.
Summary
One credit is spent for each completed lookup: a request that returns address data. From this release a charged request that returns no address data is not charged. The credit is still taken before the search runs, and is given back to your account before the response is sent, so your balance ends where it started. This follows Royal Mail's written confirmation that a well-formed postcode or address id that matches nothing in PAF is not a Transaction.
Nothing changes in your integration. Status codes, response bodies and headers are exactly as before.
What is no longer charged
| Request | Response | Before | Now |
|---|---|---|---|
GET /v1/postcodes/{postcode}, postcode not in PAF | 404 postcode_not_found | 1 credit | not charged |
GET /v1/postcodes/{postcode}?page=N beyond the last page | 200, no addresses | 1 credit | not charged |
GET /v1/addresses/{udprn}, unknown id | 404 address_not_found | 1 credit | not charged |
getAddress.io-compatible /find/{postcode}, /get/{id} | 404 Not Found | 1 credit | not charged |
getAddress.io-compatible /find/{postcode}?page=N beyond the last page | 200, no addresses | 1 credit | not charged |
Loqate-compatible Retrieve, unknown Id | 200, empty Items | 1 credit | not charged |
The credit is returned to the credit block it was taken from, so it keeps that block's expiry date. If the return could not be completed inside the request, a daily check returns it; there is no need to contact us.
Unchanged
- Each request that returns address data is a lookup, including a repeated retrieval of the same address and each page of a postcode that returns addresses. There is no retry window.
- Requests rejected before the search runs were never charged: invalid input (
400), a missing or revoked key (401), an empty balance (402/429). - A partial postcode too broad to return (
422 postcode_too_broad) still spends a credit at the time, and we return it within a few days as before. - A
500/503on a charged request gives its credit back the same way a no-match does. - Autocomplete and address-suggestion requests remain free.
Terms of Service clause 4 describes this rule; the Terms version that states it takes effect as set out in the notice sent with it.