> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Address validation

Incorrect shipping addresses are one of the most common causes of failed deliveries, expensive returns, and frustrated end consumers. Address validation lets you catch and correct address issues before a shipment is ever created, so shipments reach their destination the first time.

Sendcloud can apply two layers of validation:

| Layer                  | What it does                                                                                           | Example                                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **Formatting check**   | Ensures the address meets carrier requirements (e.g. field length limits, required postal code format) | Address line 1 is too long for PostNL → Sendcloud automatically moves overflow to address line 2 |
| **Content validation** | Verifies the address actually exists in the real world using an external address provider              | `"city": "Amstredan"` → automatically corrected to `"city": "Amsterdam"`                         |

The **formatting check** is always applied at no extra cost when you use the [Validate an address](/api/v3/address/validate) endpoint, or when creating a shipment with the [Shipments API v3](/api/v3/shipments).

**Content validation** is available as an add-on, or is included automatically depending on your contract type. See [Pricing](#pricing) for details.

<Note>Address validation is available on the **Shipments API v3** only. It is not available in API v2.</Note>

***

## How it works

There are three integration patterns depending on your use case. Choose the one that best fits your workflow.

### Option 1: Validate an address before creating a shipment

**Best for:** WMS and ERP systems that want to verify address data before announcing a shipment to a carrier.

In this flow, you call the validate endpoint first, inspect the result, correct any issues on your side, and only then create a shipment.

<Steps>
  <Step title="Send a request for validation">
    Send the address to the [Validate an address](/api/v3/address/validate) endpoint.

    ```http Example request method and URL theme={null}
    POST /api/v3/addresses/validate
    ```

    ```json Example request body theme={null}
    {
      "address": {
        "address_line_1": "Stadhuisplein",
        "house_number": "10",
        "postal_code": "5611 EM",
        "city": "Eindhoven",
        "country_code": "NL"
      },
      "carrier_code": "postnl",
      "validation_methods": ["here"]
    }
    ```
  </Step>

  <Step title="Inspect the response">
    ```json Example response theme={null}
    {
      "input_address_is_valid": true,
      "results": [
        {
          "address": {
            "address_line_1": "Stadhuisplein",
            "house_number": "10",
            "postal_code": "5611 EM",
            "city": "Eindhoven",
            "country_code": "NL"
          },
          "recommended": true,
          "analysis": {
            "validation_result": {
              "is_valid": true,
              "reasons": []
            },
            "changed_attributes": []
          }
        }
      ]
    }
    ```

    **How to read the response**

    | Field                        | What it means                                                                                                                                                                                                                                                                                                                              |
    | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `input_address_is_valid`     | Whether the submitted address passed validation. If this value is `false`, check the `reasons` array for details on the validation failure (for example: `POSTAL_CODE_MISSING`, `ADDRESS_NOT_VALID`). If this value is `null`, an upstream connection issue occurred and the service could not reach the third-party validation providers. |
    | `recommended: true`          | This is the best address match found. Use this for your shipment. There will only ever be one recommended result, or none.                                                                                                                                                                                                                 |
    | `recommended: false`         | An alternative result that passed some checks but was not the best match. Can generally be ignored.                                                                                                                                                                                                                                        |
    | `changed_attributes`         | Fields that were corrected from your input (e.g. `city`, `postal_code`). If empty and `recommended: true`, the original address was already correct.                                                                                                                                                                                       |
    | `validation_result.is_valid` | Whether the address passed validation.                                                                                                                                                                                                                                                                                                     |
    | `validation_result.reasons`  | List of reasons the address failed (e.g. `ADDRESS_NOT_VALID`, `POSTAL_CODE_MISSING`). Empty if the address is valid.                                                                                                                                                                                                                       |

    <Warning>
      An address can return `is_valid: true` but `recommended: false`. This means the address meets certain validation rules, but no confident real-world match was found. In this case, review the address manually before proceeding.
    </Warning>
  </Step>

  <Step title="Adjust your shipment">
    If a `recommended: true` result is returned, use that corrected address for your shipment.
  </Step>

  <Step title="Create your shipment">
    Create the shipment via the [Shipments API](/api/v3/shipments) using the corrected address.
  </Step>
</Steps>

### Option 2: Validate an address at checkout to suggest a correct address to your consumers

**Best for:** Individual sellers and platforms that want to guide end consumers into entering valid addresses during checkout.

In this flow, you collect partial address input from the consumer (for example, house number and postal code for Dutch addresses), call the validation endpoint, and surface the corrected or confirmed address back to the consumer before they confirm their order.

This approach ensures that by the time an order is placed, the address has already been verified, reducing failed deliveries before a single shipment is created.

<Steps>
  <Step title="Collect address data">
    Collect the relevant address fields from the consumer in your checkout (e.g. postal code + house number for NL).
  </Step>

  <Step title="Validate the address">
    Call the [Validate an address](/api/v3/address/validate) endpoint with the input.

    ```http Request method and URL theme={null}
    POST /api/v3/addresses/validate
    ```

    ```json Example request body with NL postal code and house number lookup theme={null}
    {
      "address": {
        "house_number": "10",
        "postal_code": "5611 EM",
        "country_code": "NL"
      },
      "carrier_code": "postnl",
      "validation_methods": ["here"]
    }
    ```

    The response will include a fully resolved address (street name, city, etc.) that you can present to the consumer for confirmation.
  </Step>

  <Step title="Show the results to the user">
    Display the `recommended: true` address to the consumer as a suggestion.
  </Step>

  <Step title="Final confirmation">
    Let the consumer confirm or adjust before finalising the order.
  </Step>
</Steps>

### Option 3: Inline address validation during shipment creation

**Best for:** Small sellers or merchants who want the simplest possible integration with minimal extra effort.

In this flow, you don't call the validation endpoint separately. Instead, you pass `"validation_methods": ["here"]` directly in your shipment creation request. Sendcloud will validate and, where possible, correct the address as part of the announcement.

<Steps>
  <Step title="Create a shipment">
    Create a shipment via the [Shipments API](/api/v3/shipments) and include `"validation_methods": ["here"]` in the request body.

    ```http Request method and URL theme={null}
    POST /api/v3/shipments/create-and-announce-synchronously
    ```

    ```json Example request body theme={null}
    {
      "to_address": {
        "name": "Jane Doe",
        "address_line_1": "Stadhuisplein",
        "house_number": "10",
        "postal_code": "5611 EM",
        "city": "Einhoven",
        "country_code": "NL",
        "email": "jane.doe@example.com"
      },
      "ship_with": {
        "type": "shipping_option_code",
        "properties": {
          "shipping_option_code": "postnl:standard",
          "contract_id": 517
        }
      },
      "parcels": [
        {
          "weight": { "value": "1.2", "unit": "kg" }
        }
      ],
      "validation_methods": ["here"]
    }
    ```
  </Step>

  <Step title="When a matching address is found">
    If the address can be corrected (e.g. a misspelled city), Sendcloud will automatically apply the fix.

    In this example, `"city": "Einhoven"` would be automatically corrected to `"city": "Eindhoven"`.
  </Step>

  <Step title="When no match is found">
    If no valid match can be found, the request returns an error, so you know to fix the address before retrying.
  </Step>
</Steps>

<Warning>
  **Important:** Inline validation only keeps address components it can confirm with the address provider. Any extra
  information added to address fields, such as `"address_line_2": "Ring the blue doorbell"`, will be removed if it does
  not match provider records. Use `parcels.label_notes` for delivery instructions and notes instead.
</Warning>

## Supported content validation methods

| Method | Description                                                                                                                                                                 |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `here` | Real-world address content validation using the [HERE](https://www.here.com/) address provider. Verifies that the address exists and corrects recognisable typos or errors. |

The default Sendcloud formatting check (carrier field limits, postal code format, etc.) is **always applied** regardless of which `validation_methods` you include.

***

## Pricing

The **formatting check** is included for all merchants at no additional cost.

**Content validation** (the `here` method) is free when announcing shipments on any non-enterprise subscription plan or through the shipment announcement flow with a transactional contract.

For merchants on an enterprise plan, content validation is available as a paid add-on — applicable both when using the standalone validation endpoint and when announcing shipments with a direct contract.

For full pricing details, refer to the [Sendcloud pricing page](https://www.sendcloud.com/pricing/).

***

## Related resources

* [Validate an address — API reference](/api/v3/address/validate)
* [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously)
* [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously)
* [Address field limits](/docs/addresses/address-field-limits)
* [Create a shipment](/docs/shipments/create-a-shipment)