Addresses & validation

Colonia-level addresses, validation against official catalogs, and postal code lookup.

Mexican addresses are modeled at the colonia (neighborhood) level, which is the granularity carriers work with. SendIt validates against the official SEPOMEX catalog and gives you colonia autocomplete for your forms.

Save reusable addresses

Body parameters

curl -X POST https://api.sendit.mx/v1/addresses \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "María López",
    "contactPhone": "+5213312345678",
    "contactEmail": "maria@ejemplo.mx",
    "company": "Tienda MX",
    "street": "Av. López Mateos",
    "exteriorNumber": "45",
    "interiorNumber": "B-2",
    "neighborhood": "Jardines del Sol",
    "city": "Zapopan",
    "state": "JAL",
    "postalCode": "45050",
    "country": "MX",
    "reference": "Black gate, between Av. Patria and Moctezuma",
    "isResidential": true
  }'

{
  "success": true,
  "data": {
    "id": "clx_origin_address",
    "contactName": "María López",
    "contactPhone": "+5213312345678",
    "street": "Av. López Mateos",
    "exteriorNumber": "45",
    "neighborhood": "Jardines del Sol",
    "city": "Zapopan",
    "state": "JAL",
    "postalCode": "45050",
    "country": "MX",
    "isResidential": true,
    "isDefault": false,
    "isVerified": false,
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

Use the returned id as fromAddressId / toAddressId when creating shipments. Deleting an address never affects historical shipments: each shipment freezes its own copy.

Validate an address

Verification checks the address against the SEPOMEX catalog and returns validity, confidence, and the normalized version:

curl -X POST https://api.sendit.mx/v1/address-verifications \
  -H "X-API-Key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "street": "Av. Insurgentes Sur",
      "exteriorNumber": "1235",
      "neighborhood": "Insurgentes Mixcoac",
      "postalCode": "03920",
      "city": "Ciudad de México",
      "state": "CDMX",
      "country": "MX"
    },
    "provider": "SEPOMEX"
  }'

{
  "success": true,
  "data": {
    "id": "av_1a2b3c4d5e",
    "isValid": true,
    "confidence": 0.95,
    "normalizedAddress": {
      "postalCode": "03920",
      "neighborhood": "Insurgentes Mixcoac",
      "city": "Ciudad de México",
      "state": "Ciudad de México",
      "country": "MX"
    },
    "errors": [],
    "provider": "SEPOMEX",
    "createdAt": "2026-07-17T12:00:00.000Z"
  }
}

Interpret the confidence

When several colonias share the postal code, suggestions[] carries the alternatives for your user to pick from.

Validation is advisory and never blocks shipment creation. Every verification is recorded in GET /v1/address-verifications. That record is useful evidence when a package turns out undeliverable.

For many addresses, validate up to 100 per call with POST /v1/bulk/addresses/validate. See batches.

Postal codes and colonias

Four endpoints powered by the SEPOMEX catalog, ideal for form autocomplete:

Look up a postal code

GET /v1/postal-codes/03100

{
  "success": true,
  "data": {
    "postalCode": "03100",
    "country": "MX",
    "state": { "code": "MX-CMX", "name": "Ciudad de México" },
    "municipality": "Benito Juárez",
    "city": "Ciudad de México",
    "colonies": [
      { "name": "Del Valle Centro", "type": "Colonia", "zone": "Urbano" },
      { "name": "Del Valle Norte", "type": "Colonia", "zone": "Urbano" },
      { "name": "Del Valle Sur", "type": "Colonia", "zone": "Urbano" }
    ]
  }
}

One call pre-fills city, state, and the colonia dropdown. An unknown code returns 404 RESOURCE_NOT_FOUND.

Search colonias (autocomplete)

GET /v1/postal-codes/search?q=Del+Valle&stateCode=MX-CMX&limit=10

Partial match on colonia name; optionally filter by state. Up to 50 results.

List the states

GET /v1/postal-codes/states

Returns the 32 states with their ISO 3166-2 codes (MX-JAL, MX-NLE, MX-CMX). These are the same codes the rest of the API accepts.