API Endpoint: Address Validation
The address-validation endpoint verifies a mailing address against USPS data and returns it standardized, with ZIP+4.
POST /api/v1/validate/address-validation
https://www.tincomply.com/api/v1/validate/address-validation
Verifies and standardizes a US mailing address against USPS records, adds the ZIP+4, county and congressional district, and lists every correction made to your input.
Request body
| Field | Type | Description |
|---|---|---|
streetrequired |
string | Street address line 1. |
suite |
string | Street address line 2, suite or unit. |
city |
string | City. Required unless zip5 is supplied. |
state |
string | Two-letter state abbreviation. |
zip5 |
string | 5-digit ZIP code. |
zip4 |
string | ZIP+4 extension. |
address |
string | Single-line address, as an alternative to the structured fields. |
Response object: addressValidationResult
| Field | Type | Description |
|---|---|---|
street, suite, city, state, zip5, zip4 | string | The standardized address. |
dpbc | string | Delivery point bar code. |
congressionalDistrict | string | Congressional district. |
countyName | string | County. |
latitude, longitude | number | Coordinates, when available. |
found | bool | True when USPS confirmed the address. |
corrections | string[] | Each change made to the input address. |
message | string | Human-readable summary of the result. |
completed | bool | False when the upstream source was unavailable. The request is retried automatically; call request-details with the request id later to get the finished result. |
What to do with this result
| When you see | Do this |
|---|---|
| found is true | Save the standardized address and ZIP+4 back to your record. corrections lists what changed. |
| found is false | USPS could not confirm the address. Ask the payee to confirm it before you mail checks or 1099s. |
| completed is false | The source was unavailable. Keep the request id and call request-details later; the result fills in once the retry succeeds. |
Sample request
curl -X POST https://www.tincomply.com/api/v1/validate/address-validation \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"street":"PO BOX 218","city":"YORKTOWN HEIGHTS","state":"NY","zip5":"10598"}'import requests
response = requests.post(
"https://www.tincomply.com/api/v1/validate/address-validation",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598",
},
)
response.raise_for_status()
print(response.json()["addressValidationResult"])using System.Text;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");
var body = """
{
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598"
}
""";
var response = await client.PostAsync(
"https://www.tincomply.com/api/v1/validate/address-validation",
new StringContent(body, Encoding.UTF8, "application/json"));
Console.WriteLine(await response.Content.ReadAsStringAsync());const response = await fetch("https://www.tincomply.com/api/v1/validate/address-validation", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
street: "PO BOX 218",
city: "YORKTOWN HEIGHTS",
state: "NY",
zip5: "10598",
}),
});
const data = await response.json();
console.log(data.addressValidationResult);import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598"
}
""";
HttpRequest request = HttpRequest.newBuilder(URI.create("https://www.tincomply.com/api/v1/validate/address-validation"))
.header("X-API-Key", "YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
// Parse with your JSON library (Jackson, Gson) and read addressValidationResult.
System.out.println(response.body());
}
}package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
)
func main() {
body := []byte(`{
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598"
}`)
req, err := http.NewRequest("POST", "https://www.tincomply.com/api/v1/validate/address-validation", bytes.NewReader(body))
if err != nil {
log.Fatal(err)
}
req.Header.Set("X-API-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
var data map[string]any
if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
log.Fatal(err)
}
fmt.Println(data["addressValidationResult"])
}$body = @'
{
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598"
}
'@
$response = Invoke-RestMethod -Method Post `
-Uri "https://www.tincomply.com/api/v1/validate/address-validation" `
-Headers @{ "X-API-Key" = "YOUR_API_KEY" } `
-ContentType "application/json" `
-Body $body
$response.addressValidationResultSample response
{
"id": "Pq7rT2vWx9yZa1bC3dE5fG6h",
"request": {
"street": "PO BOX 218",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598",
"requestDate": "2026-10-01T14:02:11Z",
"requestedServices": "address-validation"
},
"addressValidationResult": {
"street": "218 PO BOX",
"suite": "",
"city": "YORKTOWN HEIGHTS",
"state": "NY",
"zip5": "10598",
"zip4": "0218",
"dpbc": "18",
"congressionalDistrict": "17",
"countyName": "WESTCHESTER",
"message": "Address was confirmed as valid",
"completed": true,
"found": true,
"corrections": [ "PO BOX match.", "ZIP+4 corrected." ]
}
}Errors
Requests that cannot be processed return HTTP 400 with an object keyed by field name, each listing what was wrong. Authentication, permission and other status codes are covered in Errors & service status.
This endpoint requires an API key with the Validate permission.
See how this check works in the portal and what it costs: Address Validation