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 endpoint, or when creating a shipment with the Shipments API v3. Content validation is available as an add-on, or is included automatically depending on your contract type. See Pricing for details.

Address validation is available on the Shipments API v3 only. It is not available in API v2.

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.

Send a request for validation

Send the address to the Validate an address endpoint.

Example request method and URL

POST /api/v3/addresses/validate

Example request body

{
  "address": {
    "address_line_1": "Stadhuisplein",
    "house_number": "10",
    "postal_code": "5611 EM",
    "city": "Eindhoven",
    "country_code": "NL"
  },
  "carrier_code": "postnl",
  "validation_methods": ["here"]
}

Inspect the response

Example response

{
  "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.

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.

Adjust your shipment

If a recommended: true result is returned, use that corrected address for your shipment.

Create your shipment

Create the shipment via the Shipments API using the corrected address.

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.

Collect address data

Collect the relevant address fields from the consumer in your checkout (e.g. postal code + house number for NL).

Validate the address

Call the Validate an address endpoint with the input.

Request method and URL

POST /api/v3/addresses/validate

Example request body with NL postal code and house number lookup

{
  "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.

Show the results to the user

Display the recommended: true address to the consumer as a suggestion.

Final confirmation

Let the consumer confirm or adjust before finalising the order.

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.

Create a shipment

Create a shipment via the Shipments API and include "validation_methods": ["here"] in the request body.

Request method and URL

POST /api/v3/shipments/create-and-announce-synchronously

Example request body

{
  "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"]
}

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".

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.

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.

Supported content validation methods

Method	Description
`here`	Real-world address content validation using the HERE 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.

Getting started

Shipments

Addresses

Orders

Dynamic Checkout

Returns

Service points

Parcel tracking

Marketplaces

Archive

How it works

Option 1: Validate an address before creating a shipment

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

Option 3: Inline address validation during shipment creation

Supported content validation methods

Pricing

​How it works

​Option 1: Validate an address before creating a shipment

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

​Option 3: Inline address validation during shipment creation

​Supported content validation methods

​Pricing

​Related resources

How it works

Option 1: Validate an address before creating a shipment

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

Option 3: Inline address validation during shipment creation

Supported content validation methods

Pricing

Related resources