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

# Validate an address

> Tells you what to do with an address before you calculate tax for it, and what a calculation makes of it. Taxwire normalizes the address, checks its ZIP code against its state, and looks it up the way a calculation would.

`recommended_action` is about the address alone.

`tax` is about the calculation. It follows the address to the tax jurisdiction it lands in.

Each issue has a `code` and `params` you can build or translate your own message from. When Taxwire suggests a change, `suggested_address` holds the address with every suggestion applied.

Validating an address before you calculate makes the calculation faster: Taxwire remembers the lookup, so a calculation for the same address, spelled exactly the same way, skips it. When every issue is `info`, the suggested spelling is remembered too.

> [!NOTE]
>
> This endpoint is enabled per account. Until it is enabled for yours, it returns `404`. Contact us to turn it on.

When a calculation for an address comes to 0 because of where it is, an issue says why: see [Addresses and zero tax](https://apidocs.taxwire.com/api-reference/faq.md#addresses-and-zero-tax) in the FAQ.

## Issue codes

Each issue has a `code` and `params`, the values its `message` is built from. A code always carries the same `params` keys, so you can write or translate your own message. The wording of `message` may change.

| Code | Severity | When | `params` |
| - | - | - | - |
| `address_empty` | error | Every field is blank. | |
| `address_incomplete` | error | There isn't enough of the address to tell where it is. | |
| `address_not_found` | error | No geocoder finds it, and nothing else places it. | |
| `state_missing` | error, warning | A US or Canadian address has no state or province, and nothing to infer one from. An error when there's nothing else to place it by. A warning when there is: a Canadian address with nothing but the country (a calculation still charges the federal GST), or a city or street with no state and no postal code, which is found, but with nothing to check it lands where you meant. | |
| `city_missing` | error, warning | An Illinois address with only a state. Chicago is taxed differently from the rest of Illinois. A warning when the country is US, since a calculation then taxes it in Chicago. | |
| `state_postal_code_mismatch` | warning | The ZIP code belongs to another state. The ZIP code's state is suggested. | `postal_code`, `postal_code_state`, `state` |
| `street_not_found` | warning | No geocoder finds the street, so the address is placed at the center of a ZIP code. | `postal_code` |
| `street_approximate` | warning | No geocoder could pin the street down, so the address is placed at the closest match one found. | |
| `jurisdiction_not_found` | warning | Found, but in no tax jurisdiction Taxwire knows. | |
| `location_state_mismatch` | warning | Found in another state than the address names. | `state`, `located_state` |
| `location_country_mismatch` | warning | Found in another country than the address names. | `country`, `located_country` |
| `postal_code_invalid_format` | warning | Not a US ZIP code format. | `postal_code` |
| `postal_code_unassigned` | warning | The ZIP code belongs to no state. | `postal_code` |
| `postal_code_inactive` | warning | Not on the USPS list of ZIP codes in use. It may be new. | `postal_code` |
| `country_missing` | warning | No country, and none could be worked out. | |
| `postal_code_missing` | info | No ZIP code. The address isn't wrong, only less complete; when that makes the tax approximate, `street_missing` says so. | |
| `street_missing` | info | No street, so the address is placed at the center of a ZIP code: its own, or with none, its state's most populous one. | `postal_code` |
| `location_not_supported` | info | Taxwire doesn't calculate tax there: a country it doesn't cover, or a place where every rate is 0, such as Armed Forces mail or Guam. `region` is a country's ISO code (`BR`), or a US state or territory code (`MP`). When the country the address names decides it, `field` is `country` and the address isn't looked up; when the lookup finds the address there, `field` is null. | `region` |
| `no_sales_tax` | info | No sales tax there by law. | `state` |
| `components_split` | info | The address was crammed into too few fields, so Taxwire split it into its parts. | |
| `state_normalized` | info | A state written as a name, such as `Nevada` for `NV`. | `value`, `normalized` |
| `country_normalized` | info | A country written as a name, such as `USA` for `US`. | `value`, `normalized` |
| `state_inferred` | info | The state was filled in from the ZIP code. | `inferred` |
| `country_inferred` | info | The country was filled in from the state or ZIP code. | `inferred` |

New codes may be added. Treat an unknown code by its `severity`.


## OpenAPI

````yaml POST /addresses/validate
openapi: 3.1.0
info:
  title: Taxwire Public API
  version: 0.1.0
servers: []
security: []
paths:
  /addresses/validate:
    post:
      tags:
        - Addresses
      summary: Validate an Address
      description: >-
        Tells you what to do with an address before you calculate tax for it,
        and what a calculation makes of it. Taxwire normalizes the address,
        checks its ZIP code against its state, and looks it up the way a
        calculation would.


        `recommended_action` is about the address alone.


        `tax` is about the calculation. It follows the address to the tax
        jurisdiction it lands in.


        Each issue has a `code` and `params` you can build or translate your own
        message from. When Taxwire suggests a change, `suggested_address` holds
        the address with every suggestion applied.


        Validating an address before you calculate makes the calculation faster:
        Taxwire remembers the lookup, so a calculation for the same address,
        spelled exactly the same way, skips it. When every issue is `info`, the
        suggested spelling is remembered too.
      operationId: validate_address_route_addresses_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressValidationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressValidation'
              examples:
                accept:
                  summary: Accept
                  value:
                    object: address_validation
                    recommended_action: accept
                    tax:
                      calculated: true
                      precision: exact
                    issues: []
                confirm:
                  summary: 'Confirm: the ZIP code and state disagree'
                  value:
                    object: address_validation
                    recommended_action: confirm
                    tax:
                      calculated: true
                      precision: exact
                    suggested_address:
                      line1: 1 S Virginia St
                      city: Reno
                      state: NV
                      postal_code: '89501'
                      country: US
                    issues:
                      - code: state_postal_code_mismatch
                        severity: warning
                        field: state
                        message: >-
                          ZIP code 89501 is in NV, not CA. Taxwire places the
                          address by its street and ZIP code, so the state you
                          sent doesn't change the tax, but check which one is
                          right.
                        params:
                          postal_code: '89501'
                          postal_code_state: NV
                          state: CA
                        suggested_value: NV
                accept_approximate:
                  summary: Accept, with tax at the ZIP code's center
                  value:
                    object: address_validation
                    recommended_action: accept
                    tax:
                      calculated: true
                      precision: approximate
                    suggested_address:
                      city: Austin
                      state: TX
                      postal_code: '78701'
                      country: US
                    issues:
                      - code: state_normalized
                        severity: info
                        field: state
                        message: The state 'Texas' is written as 'TX'.
                        params:
                          value: Texas
                          normalized: TX
                        suggested_value: TX
                      - code: street_missing
                        severity: info
                        field: line1
                        message: >-
                          Without a street address, tax is calculated at the
                          center of ZIP code 78701, which may straddle tax
                          jurisdictions. Add the street address for an exact
                          rate.
                        params:
                          postal_code: '78701'
                confirm_not_calculated:
                  summary: 'Confirm: the address lands in no tax jurisdiction'
                  value:
                    object: address_validation
                    recommended_action: confirm
                    tax:
                      calculated: false
                    issues:
                      - code: jurisdiction_not_found
                        severity: warning
                        message: >-
                          Taxwire found this address outside every tax
                          jurisdiction it knows, so tax is 0. Check the address.
                        params: {}
                accept_no_sales_tax:
                  summary: Accept, where there is no sales tax
                  value:
                    object: address_validation
                    recommended_action: accept
                    tax:
                      calculated: true
                      precision: exact
                    issues:
                      - code: no_sales_tax
                        severity: info
                        message: >-
                          There's no sales tax where this address is in OR, so
                          tax is 0.
                        params:
                          state: OR
                accept_not_calculated:
                  summary: Accept, in a country Taxwire doesn't calculate tax for
                  value:
                    object: address_validation
                    recommended_action: accept
                    tax:
                      calculated: false
                    issues:
                      - code: location_not_supported
                        severity: info
                        field: country
                        message: >-
                          Taxwire doesn't calculate tax in BR, so tax is 0. The
                          address wasn't looked up.
                        params:
                          region: BR
                fix:
                  summary: Fix
                  value:
                    object: address_validation
                    recommended_action: fix
                    tax:
                      calculated: false
                    issues:
                      - code: state_missing
                        severity: error
                        field: state
                        message: >-
                          The address has no state, province, or postal code.
                          Add the state or a ZIP / postal code.
                        params: {}
        '422':
          description: Validation Error - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - status: '422'
                    code: validation_required_field
                    title: Missing quantity
                    detail: Please provide a value for the required quantity field
                    source:
                      pointer: /data/attributes/line_items/0/quantity
        '429':
          description: Rate limit exceeded. Try again later.
          headers:
            Retry-After:
              description: Time in seconds until the rate limit resets
              schema:
                type: string
            X-RateLimit-Limit:
              description: The rate limit ceiling for the given request
              schema:
                type: string
            X-RateLimit-Remaining:
              description: The number of requests remaining in the time window
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - status: '429'
                    code: rate_limit_error
                    title: Too Many Requests
                    detail: Rate limit exceeded
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - status: '500'
                    code: system_internal_error
                    title: Internal Error
                    detail: An unexpected error occurred. Our team has been notified.
        '503':
          description: >-
            The address lookup is unavailable. Retry after the number of seconds
            in `Retry-After`.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - status: '503'
                    code: system_service_unavailable
                    title: Service Unavailable
                    detail: >-
                      Taxwire couldn't look the address up right now. Try again
                      shortly.
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    AddressValidationRequest:
      properties:
        address:
          $ref: '#/components/schemas/AddressValidationAddress'
          description: The address to validate.
      additionalProperties: false
      type: object
      required:
        - address
      title: AddressValidationRequest
      description: Body of POST /addresses/validate.
    AddressValidation:
      properties:
        object:
          type: string
          const: address_validation
          title: Object
          default: address_validation
        recommended_action:
          $ref: '#/components/schemas/RecommendedAction'
          description: >-
            What to do with the address, judged on the address alone. `accept`:
            use it as it is. `confirm`: something about it may be wrong; confirm
            it, or use `suggested_address`. `fix`: it can't be placed; the
            `error` issues say why.
        tax:
          $ref: '#/components/schemas/TaxOutcome'
          description: What a tax calculation does with the address as sent.
        suggested_address:
          anyOf:
            - $ref: '#/components/schemas/SuggestedAddress'
            - type: 'null'
          description: >-
            The address with every suggestion applied, when Taxwire suggests a
            change. The rest of the answer is about the address as you sent it.
        issues:
          items:
            $ref: '#/components/schemas/AddressIssue'
          type: array
          title: Issues
          description: Everything wrong with, or changed in, the address.
      type: object
      required:
        - recommended_action
        - tax
      title: AddressValidation
      description: ''
    ErrorResponse:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
          title: Errors
      type: object
      required:
        - errors
      title: ErrorResponse
      description: Standardized JSON:API error response model.
    AddressValidationAddress:
      properties:
        line1:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Line1
          examples:
            - 1 S Virginia St
        line2:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Line2
        city:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: City
          examples:
            - Reno
        state:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: State
          description: The state, province or region, as a code or a name.
          examples:
            - NV
        postal_code:
          anyOf:
            - type: string
              maxLength: 20
            - type: 'null'
          title: Postal Code
          examples:
            - '89501'
        country:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Country
          description: >-
            The country, as an ISO 3166-1 alpha-2 code or a name. An address
            with no country is taken as a US address.
          examples:
            - US
      additionalProperties: false
      type: object
      title: AddressValidationAddress
      description: A postal address.
    RecommendedAction:
      type: string
      enum:
        - accept
        - confirm
        - fix
      title: RecommendedAction
      description: What the caller should do with the address, judged on the address alone.
    TaxOutcome:
      properties:
        calculated:
          type: boolean
          title: Calculated
          description: >-
            Whether Taxwire calculates tax for the address. False where a
            calculation charges no tax because of where the address is: a
            country or territory Taxwire doesn't cover, or a place that lies in
            no tax jurisdiction Taxwire knows. Also false when the address must
            be fixed first. True where there is no sales tax by law, since
            Taxwire calculates it as 0 there (a `no_sales_tax` issue says so).
        precision:
          anyOf:
            - $ref: '#/components/schemas/TaxPrecision'
            - type: 'null'
          description: >-
            `exact`: the tax is the one at this address, because Taxwire placed
            the street, or a ZIP code, city or state that lies wholly in one set
            of tax jurisdictions. `approximate`: the address is placed near it
            rather than at it (the center of its ZIP code, or the closest match
            to a street no geocoder could pin down), which may straddle
            jurisdictions. Null when no tax is calculated.
      type: object
      required:
        - calculated
      title: TaxOutcome
      description: ''
    SuggestedAddress:
      properties:
        line1:
          anyOf:
            - type: string
            - type: 'null'
          title: Line1
        line2:
          anyOf:
            - type: string
            - type: 'null'
          title: Line2
        city:
          anyOf:
            - type: string
            - type: 'null'
          title: City
        state:
          anyOf:
            - type: string
            - type: 'null'
          title: State
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
      type: object
      title: SuggestedAddress
      description: ''
    AddressIssue:
      properties:
        code:
          $ref: '#/components/schemas/AddressIssueCode'
          description: What the issue is. New codes may be added.
        severity:
          $ref: '#/components/schemas/AddressIssueSeverity'
          description: >-
            `error`: the address can't be placed, so it must be fixed.
            `warning`: the address may be wrong; confirm it. `info`: cosmetic,
            such as a name written as its code. The most severe issue sets
            `recommended_action`.
        field:
          anyOf:
            - type: string
              enum:
                - line1
                - line2
                - city
                - state
                - postal_code
                - country
            - type: 'null'
          title: Field
          description: The address field the issue is about, if one.
        message:
          type: string
          title: Message
          description: >-
            A human-readable explanation of the issue. Its wording may change;
            build your own from `code` and `params` if you need control over it.
          examples:
            - ZIP code 89501 is in NV, not CA.
        params:
          additionalProperties:
            type: string
          type: object
          title: Params
          description: >-
            The values the message is built from, so you can write or translate
            your own. Each code always carries the same keys: `postal_code`,
            `postal_code_state` and `state` for `state_postal_code_mismatch`;
            `postal_code` for the other ZIP code issues, and for
            `street_missing` and `street_not_found` (the ZIP the address is
            placed at); `country` and `located_country` for
            `location_country_mismatch`; `state` and `located_state` for
            `location_state_mismatch`; `region` for `location_not_supported` (a
            country's ISO code, or a US state or territory code); `state` for
            `no_sales_tax`; `value` and `normalized` for `state_normalized` and
            `country_normalized`; `inferred` for `state_inferred` and
            `country_inferred`. Other codes carry none.
          examples:
            - postal_code: '89501'
              postal_code_state: NV
              state: CA
        suggested_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Value
          description: >-
            The value Taxwire suggests for `field`, already applied in
            `suggested_address`.
          examples:
            - NV
      type: object
      required:
        - code
        - severity
        - message
      title: AddressIssue
      description: ''
    Error:
      properties:
        status:
          type: string
          title: Status
        code:
          type: string
          title: Code
        title:
          type: string
          title: Title
        detail:
          type: string
          title: Detail
        source:
          anyOf:
            - $ref: '#/components/schemas/ErrorSource'
            - type: 'null'
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Meta
      type: object
      required:
        - status
        - code
        - title
        - detail
      title: Error
      description: Individual JSON:API error object.
    TaxPrecision:
      type: string
      enum:
        - exact
        - approximate
      title: TaxPrecision
      description: Whether the tax is calculated at the address or near it.
    AddressIssueCode:
      type: string
      enum:
        - address_empty
        - address_incomplete
        - address_not_found
        - city_missing
        - components_split
        - country_inferred
        - country_missing
        - country_normalized
        - jurisdiction_not_found
        - location_country_mismatch
        - location_not_supported
        - location_state_mismatch
        - no_sales_tax
        - postal_code_inactive
        - postal_code_invalid_format
        - postal_code_missing
        - postal_code_unassigned
        - state_inferred
        - state_missing
        - state_normalized
        - state_postal_code_mismatch
        - street_approximate
        - street_missing
        - street_not_found
      title: AddressIssueCode
      description: What is wrong with, or was changed in, an address.
    AddressIssueSeverity:
      type: string
      enum:
        - error
        - warning
        - info
      title: AddressIssueSeverity
      description: |-
        How much an issue matters; the worst one sets the recommended action.

        An error means the address can't be placed (fix). A warning means it may
        be wrong, so a person should confirm it (confirm). Info is cosmetic.
    ErrorSource:
      properties:
        pointer:
          anyOf:
            - type: string
            - type: 'null'
          title: Pointer
      type: object
      title: ErrorSource
      description: Identifies the source of the error, e.g., via a JSON Pointer.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.