---
title: "Suggestions"
method: POST
path: "/v1/address_validation/suggestions"
tags: ["Address Validation"]
---

# Suggestions

`POST /v1/address_validation/suggestions`

This API endpoint provides address suggestions based on
    partial input data. It helps users auto-complete and validate addresses efficiently
    by returning a list of suggested addresses that match the input criteria.
    This improves accuracy, increases speed, reduces errors,
    and streamlines the data entry process.

## Headers

- `x-organization-id` string, nullable, required — The unique identifier for the organization making the request

## Request body

- ValidationAddress
  - `line1` string, nullable — Primary address line, such as street name and number
  - `line2` string, nullable — Additional address details, such as an apartment or suite number
  - `line3` string, nullable — Additional address details for complex addresses
  - `city` string, nullable — The city or town name for the address
  - `state` string, nullable — State, province, or region of the address
  - `country` string, nullable — Country code in ISO 3166-1 alpha-2 format (e.g., 'US' for the United States). Defaults to 'US'. should not be empty. Not validating here as the validation structure can be different for different providers
  - `postalCode` string, nullable — ZIP or postal code for the address. Can be empty for some locales. Not validating here as the validation structure can be different for different providers
  - `id` integer, nullable — Unique identifier for the request, if applicable
  - `county` string, nullable — County or district name for the address
  - `fullAddress` string, nullable — A complete address string that can be used as an alternative to providing individual fields.

## Response `200`

Successfully retrieved address suggestions

- unknown

## Other responses

- `401` — The request is missing a valid x-api-key.
- `422` — Validation error - Address fields failed validation or are incomplete
- `500` — An unexpected server error occurred.

## Changes

- **2026-08-29** `6ba4f4c774c3` — 1 breaking, 1 warning, 12 info
  - added the new required `header` request parameter `x-organization-id`
  - removed the request property `full_address`
  - the endpoint scheme security `APIKeyHeader` was added to the API
  - the endpoint scheme security `APIKeyHeader AND CustomHeader` was removed from the API
  - …10 more
  - …this revision’s changelog is incomplete

[Change history](https://skmtc.dev/trykintsugi/apis/tax-platform/changes/v1/address_validation/suggestions/post.md)

---

[API](https://skmtc.dev/trykintsugi/apis/tax-platform.md) · [All operations](https://skmtc.dev/trykintsugi/apis/tax-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/trykintsugi/tax-platform/revisions/6ba4f4c774c3/schema)