Find addresses

Search for address suggestions from a free-text query.

Use this endpoint as step 1 in an assisted address-entry flow.

Request guidance:

• Provide a user-entered text value such as postcode, street name, or partial address.
• Provide container when refining from a previous response.
• Include a valid bearer token; this is an authenticated user endpoint.

Recommended flow:

1. Call POST /user/addresses/lookup/find with text from the user input.
2. If container-type results are returned, call this endpoint again with container to drill down.
3. When an address result is selected, call POST /user/addresses/lookup/retrieve with its id.
4. Persist the final address with POST /user/addresses.

Behavior notes:

• Returns suggestions only; no address is saved to the account.
• Responses may include both final addresses and intermediate container nodes.
• Empty results are valid and should be handled in UI as "no matching addresses found".