> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # Validate order address > Use this endpoint to validate a shipping address before placing an order. Use this when end users are entering shipping addresses in your platform UI - validating up front catches errors early and reduces fulfillment failures. ###### Required fields: - `address` - the address object to validate. Contains: - `address1` - street address (validated as required) - `address2` - apartment, suite, floor (optional) - `city` - city name (validated as required) - `provinceCode` - state or province code (1-3 uppercase alphanumeric characters) - `postalCode` - postal/ZIP code (alphanumeric, 3-10 characters) - `countryCode` - two-letter uppercase country code ###### Optional parameters: - `Request-Source` header - source of the request (api_native, api_zapier, api_salesforce, api_ftp, api_make) ###### Please note: - Successful validation returns one of two `result` values: - `verified` - the address is correct and deliverable - `ambiguous` - the address was found but with ambiguity (e.g. multiple matches). Consider surfacing the response message to the end user to confirm before proceeding. - Returns `400` with a per-field errors array when address validation fails (e.g. invalid address format, missing required fields). Each entry includes the offending path, a human-readable message, and the errorCode. - Returns `422` when the address is well-formed but cannot be found by the validation service. - This endpoint does not place an order - it's a pre-flight check. Always follow up with placing an order once validation succeeds. #### Permissions - Requires: `orders:read:masked` or `orders:read:unmasked` ## OpenAPI ````yaml post /v3/orders/addresses/validate openapi: 3.0.3 info: title: Snappy Public API v3 version: 3.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Products description: >- Use these endpoints to retrieve products and tags for building catalog and browse experiences in your UI. - name: Collections description: >- Use these endpoints to retrieve products within curated collections for marketplace and browse experiences. - name: Variants description: >- Use these endpoints to retrieve variants, variant pricing, and country availability for orderable product SKUs. - name: Billing Methods description: >- A **Billing Method** is the funding source attached to an **Account** - for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit Card. Use these endpoints to retrieve billing method details such as remaining balance, status, and expiration. - name: Accounts description: >- An **Account** is a sub-entity within a **Company**, used to organize campaigns and gift sends. Use these endpoints to list, retrieve, and create accounts. - name: API Keys description: >- Use these endpoints to manage API keys for programmatic access. Key management requires company owner privileges. - name: Orders description: >- Use these endpoints to place, retrieve, cancel, and validate orders and shipping addresses. paths: /v3/orders/addresses/validate: post: tags: - Orders summary: Validate order address description: >- Use this endpoint to validate a shipping address before placing an order. Use this when end users are entering shipping addresses in your platform UI - validating up front catches errors early and reduces fulfillment failures. ###### Required fields: - `address` - the address object to validate. Contains: - `address1` - street address (validated as required) - `address2` - apartment, suite, floor (optional) - `city` - city name (validated as required) - `provinceCode` - state or province code (1-3 uppercase alphanumeric characters) - `postalCode` - postal/ZIP code (alphanumeric, 3-10 characters) - `countryCode` - two-letter uppercase country code ###### Optional parameters: - `Request-Source` header - source of the request (api_native, api_zapier, api_salesforce, api_ftp, api_make) ###### Please note: - Successful validation returns one of two `result` values: - `verified` - the address is correct and deliverable - `ambiguous` - the address was found but with ambiguity (e.g. multiple matches). Consider surfacing the response message to the end user to confirm before proceeding. - Returns `400` with a per-field errors array when address validation fails (e.g. invalid address format, missing required fields). Each entry includes the offending path, a human-readable message, and the errorCode. - Returns `422` when the address is well-formed but cannot be found by the validation service. - This endpoint does not place an order - it's a pre-flight check. Always follow up with placing an order once validation succeeds. #### Permissions - Requires: `orders:read:masked` or `orders:read:unmasked` parameters: - schema: type: string description: Optional account identifier for swag validation/filtering. example: acc123456 required: false description: Optional account identifier for swag validation/filtering. name: snappy-account-id in: header - schema: type: string description: Optional company identifier for swag validation/filtering. example: cmp123456 required: false description: Optional company identifier for swag validation/filtering. name: snappy-company-id in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateOrderAddressV3Body' responses: '200': description: Address validation result. content: application/json: schema: $ref: '#/components/schemas/ValidateOrderAddressV3Response' '400': description: Bad Request - Invalid request body. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' '422': description: Unprocessable Entity - Address could not be validated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' security: - ApiKeyAuthentication: [] components: schemas: ValidateOrderAddressV3Body: type: object properties: address: $ref: '#/components/schemas/PlaceOrderV3ShippingAddress' required: - address additionalProperties: false description: Validate order address request body. example: address: address1: 123 Main St address2: Apt 4B city: New York provinceCode: NY postalCode: '10001' countryCode: US ValidateOrderAddressV3Response: type: object properties: data: $ref: '#/components/schemas/ValidateOrderAddressV3Result' required: - data description: Address validation response. ErrorResponseV3: type: object properties: message: type: string description: Human-readable error message. example: Product not found. errorCode: type: string description: Structured error code. example: 404_PROD_001 errors: type: array items: type: object properties: message: type: string example: Product with id 'q1w2e3r4t5' was not found path: type: string description: Dot-separated path to the field that caused the error. example: pathParameters.productId errorCode: type: string example: 404_PROD_001 required: - message - path description: Optional field-level error details. required: - message - errorCode description: Standard v3 error envelope. PlaceOrderV3ShippingAddress: type: object properties: address1: type: string minLength: 1 maxLength: 35 description: >- Street address, including house or building number. Maximum 35 characters. example: 123 Main St address2: type: string maxLength: 35 description: >- Apartment, suite, floor, or other secondary address details. Maximum 35 characters. example: Apt 4B city: type: string minLength: 1 description: City name. example: New York provinceCode: type: string pattern: ^[A-Z0-9]{1,3}$ description: >- State or province code. Must be 1-3 uppercase alphanumeric characters (e.g., US state codes like NY, CA, or Australian territories like NSW). example: NY postalCode: type: string pattern: ^[a-zA-Z0-9 -]{3,10}$ description: Postal code or ZIP code. Alphanumeric, 3-10 characters. example: '10001' countryCode: type: string pattern: ^[A-Z]{2}$ description: Two-letter ISO 3166-1 alpha-2 country code. Must be uppercase. example: US required: - address1 - city - provinceCode - postalCode - countryCode additionalProperties: false description: Physical shipping address for order delivery. example: address1: 123 Main St address2: Apt 4B city: New York provinceCode: NY postalCode: '10001' countryCode: US ValidateOrderAddressV3Result: type: object properties: message: type: string description: Validation result message. example: The address is correct result: type: string enum: - verified - ambiguous description: The validation result status. example: verified required: - message - result description: Address validation result. securitySchemes: ApiKeyAuthentication: type: apiKey in: header name: X-Api-Key description: |- ## Company Level Authentication Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_API_KEY ``` ````