Boxc ValidateAddress API

openapi: 3.2.0
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Validate Address API
  version: '1.123'
  description: 'A simple but powerful logistics API that drives international ecommerce by utilizing a single integration with access to dozens of carriers and global markets. BoxC can complete every leg or only select steps of a shipment''s journey on your behalf with our routing engine.

    '
servers:
- url: https://api.boxc.com/v1
tags:
- name: ValidateAddress
  x-displayName: Validate Address
  description: The Validate Address resource permits a user to validate and retrieve the most likely matches of provided postal addresses. Each successful validation costs $0.03 (USD).
paths:
  /validate-address:
    post:
      tags:
      - ValidateAddress
      summary: POST /validate-address
      description: Get validated possible matches of provided postal addresses.
      operationId: validateAddress
      security:
      - JWT:
        - validate
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/validate-address \\\n  -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"addresses\": [\n      {\n        \"street1\": \"113 INTL BROADWAY\",\n        \"street2\": \"\",\n        \"city\": \"LOS ANGELES\",\n        \"province\": \"CA\",\n        \"postal_code\": \"91013\",\n        \"country\": \"US\"\n      }\n    ]\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  type: array
                  items:
                    $ref: '#/components/schemas/ValidateAddress'
              required:
              - addresses
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  addresses:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValidatedAddress'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                validation:
                  summary: Validation error
                  description: The request schema is invalid.
                  value:
                    code: 1000
                    message: Request is malformed.
                    status: error
                    errors:
                    - Request is malformed.
                addressError:
                  summary: Address Validation
                  description: Unable to validate address due to an error
                  value:
                    code: 1425
                    message: Unable to validate address due to an error
                    errors:
                    - Unable to validate address due to an error
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '402':
          $ref: '#/components/schemas/PaymentRequired'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '429':
          $ref: '#/components/schemas/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                balanceError:
                  summary: Server Error - Retrieving Balance
                  description: There was an error while fetching the account balance
                  value:
                    code: 1081
                    message: There was an error while fetching the account balance
                    errors:
                    - There was an error while fetching the account balance
                chargingError:
                  summary: Server Error - Charging Account
                  description: There was an error while charging the account balance
                  value:
                    code: 1082
                    message: There was an error while charging the account balance
                    errors:
                    - There was an error while charging the account balance
components:
  schemas:
    validated-address-match:
      type: object
      properties:
        street1:
          description: The street address.
          type: string
          maxLength: 50
          example: 113 INTL BROADWAY
        street2:
          description: Additional space for street address.
          type: string
          maxLength: 50
          example: ''
        city:
          type: string
          description: The city.
          example: LOS ANGELES
        province:
          type: string
          description: The province or the state. Optional. Required for US.
          example: CA
        postal_code:
          type: string
          description: The postal code or ZIP Code.
          example: 90210
        country:
          type: string
          description: The country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
          example: US
        confidence:
          type: string
          description: 'Confidence value inside each match describes how accurate the match is. You can increase the confidence of an existing match by providing additional or more accurate information.


            LOW confidence means that the address is most probably does not exist thus, it should not be provided as an address input to any of our endpoints.


            MEDIUM confidence means that the address is missing some components or some parts are unconfirmed but plausible. It is usually acceptable as an address input but whether it can be used or not depends on its completeness thus, caution is advised.


            HIGH confidence means that there''s an exact match thus, it is recommended and can be used as an address input. '
          example: HIGH
          enum:
          - LOW
          - MEDIUM
          - HIGH
        verdict:
          type: object
          description: High level overview of the address validation result.
          properties:
            inputGranularity:
              type: string
              description: The various granularities that an address can have.
              example: PREMISE
              enum:
              - GRANULARITY_UNSPECIFIED
              - SUB_PREMISE
              - PREMISE
              - PREMISE_PROXIMITY
              - BLOCK
              - ROUTE
              - OTHER
            validationGranularity:
              type: string
              description: The level of granularity for the post-processed address that the API can fully validate.
              example: SUB_PREMISE
              enum:
              - GRANULARITY_UNSPECIFIED
              - SUB_PREMISE
              - PREMISE
              - PREMISE_PROXIMITY
              - BLOCK
              - ROUTE
              - OTHER
            geocodeGranularity:
              type: string
              description: How coarse or fine the geocoded location is.
              example: PREMISE_PROXIMITY
              enum:
              - GRANULARITY_UNSPECIFIED
              - SUB_PREMISE
              - PREMISE
              - PREMISE_PROXIMITY
              - BLOCK
              - ROUTE
              - OTHER
            addressComplete:
              type: boolean
              description: The post-processed address is considered complete if there are no unresolved tokens, no unexpected or missing address components. If unset, indicates that the value is false.
              example: true
            hasUnconfirmedComponents:
              type: boolean
              description: At least one address component cannot be categorized or validated.
              example: false
            hasInferredComponents:
              type: boolean
              description: At least one address component was added that wasn't in the input.
              example: true
            hasReplacedComponents:
              type: boolean
              description: At least one address component was replaced.
              example: false
            possibleNextAction:
              type: string
              description: An interpretive summary of the API response that should not be considered as a guarantee of accuracy.
              example: ACCEPT
              enum:
              - POSSIBLE_NEXT_ACTION_UNSPECIFIED
              - FIX
              - CONFIRM_ADD_SUBPREMISES
              - CONFIRM
              - ACCEPT
            hasSpellCorrectedComponents:
              type: boolean
              description: At least one address component was spell-corrected.
              example: true
        addressComponents:
          description: List of address components such as a street, city, or state.
          type: array
          items:
            type: object
            properties:
              componentName:
                type: object
                description: A wrapper for the name of the component.
                properties:
                  text:
                    type: string
                    description: The name text.
                    example: Main St.
                  languageCode:
                    type: string
                    description: Two letter language code.
                    example: en
              componentType:
                type: string
                description: The type of the address component.
                example: street_number
              confirmationLevel:
                type: string
                description: Indicates the level of certainty that the component is correct.
                example: CONFIRMED
                enum:
                - CONFIRMATION_LEVEL_UNSPECIFIED
                - CONFIRMED
                - UNCONFIRMED_BUT_PLAUSIBLE
                - UNCONFIRMED_AND_SUSPICIOUS
        missingComponentTypes:
          description: The types of components that were expected to be present in a correctly formatted mailing address but were not found in the input AND could not be inferred.
          type: array
          example:
          - street_address
          - postal_code
          items:
            type: string
        unconfirmedComponentTypes:
          description: The types of the components that are present in the addressComponents but could not be confirmed to be correct.
          type: array
          example:
          - subpremise
          - route
          items:
            type: string
        unresolvedTokens:
          description: Input that was not recognized as a valid part of an address.
          type: array
          example:
          - Box
          - '11789'
          items:
            type: string
        metadata:
          type: object
          description: The metadata for the post-processed address.
          properties:
            business:
              type: boolean
              description: Is the address for a business.
              example: false
            poBox:
              type: boolean
              description: Is the address a PO box.
              example: false
            residential:
              type: boolean
              description: Is the address a residence.
              example: true
        uspsData:
          type: object
          description: The USPS data for the address.
          properties:
            standardizedAddress:
              type: object
              description: USPS representation of a US address.
              properties:
                firstAddressLine:
                  type: string
                  description: First address line.
                  example: 123 Main St.
                firm:
                  type: string
                  description: The firm's name.
                  example: IBM Corp.
                secondAddressLine:
                  type: string
                  description: Second address line.
                  example: Apt. 3B
                urbanization:
                  type: string
                  description: Puerto Rican urbanization name.
                  example: Urbanización Valle Verde
                cityStateZipAddressLine:
                  type: string
                  description: City, state and postal code.
                  example: 10123
                city:
                  type: string
                  description: The address city.
                  example: New Orleans
                state:
                  type: string
                  description: The two letter address state abbreviation.
                  example: LA
                zipCode:
                  type: string
                  description: Postal code.
                  example: 70112
                zipCodeExtension:
                  type: string
                  description: 4-digit postal code extension.
                  example: 2431
            deliveryPointCode:
              type: string
              description: 2 digit delivery point code
              example: 12
            deliveryPointCheckDigit:
              type: string
              description: The delivery point check digit
              example: 8
            dpvConfirmation:
              type: string
              description: The possible values for DPV confirmation.
              example: Y
              enum:
              - N
              - D
              - S
              - Y
              - Empty
            dpvFootnote:
              type: string
              description: The footnotes from delivery point validation.
              example: AA
              enum:
              - AA
              - A1
              - BB
              - CC
              - C1
              - N1
              - M1
              - M3
              - P1
              - P3
              - F1
              - G1
              - U1
              - PB
              - RR
              - R1
              - R7
              - IA
              - TA
            dpvCmra:
              type: string
              description: Is the address a Commercial Mail Receiving Agency?
              example: N
            dpvVacant:
              type: string
              description: Is this a vacant address?
              example: N
            dpvNoStat:
              type: string
              description: No stat addresses are ones which are not continuously occupied or addresses that the USPS does not service.
              example: N
            dpvNoStatReasonCode:
              type: integer
              description: No stat type.
              example: 1
            dpvDrop:
              type: string
              description: Flag indicates mail is delivered to a single receptable at a site.
              example: Y
            dpvThrowback:
              type: string
              description: Indicates that mail is not delivered to the street address.
              example: N
            dpvNonDeliveryDays:
              type: string
              description: Flag indicates mail delivery is not performed every day of the week.
              example: N
            dpvNonDeliveryDaysValues:
              type: integer
              description: Integer identifying non-delivery days.
              example: 1
            dpvNoSecureLocation:
              type: string
              description: Flag indicates door is accessible, but package will not be left due to security concerns.
              example: N
            dpvPbsa:
              type: string
              description: Indicates the address was matched to PBSA record.
              example: Y
            dpvEnhancedDeliveryCode:
              type: string
              description: Indicates that more than one DPV return code is valid for the address.
              example: D
              enum:
              - Y
              - N
              - S
              - D
              - R
            carrierRoute:
              type: string
              description: The four character carrier route code.
              example: R008
            carrierRouteIndicator:
              type: string
              description: Carrier route rate sort indicator.
              example: D
            ewsNoMatch:
              type: boolean
              description: The delivery address is matchable, but the EWS file indicates that an exact match will be available soon.
              example: true
            postOfficeCity:
              type: string
              description: Main post office city.
              example: Miami
            postOfficeState:
              type: string
              description: Main post office state abbreviation.
              example: FL
            abbreviatedCity:
              type: string
              description: Abbreviated city.
              example: LA
            fipsCountyCode:
              type: string
              description: FIPS county code.
              example: 111
            county:
              type: string
              description: County name
              example: Dade
            elotNumber:
              type: string
              description: Enhanced Line of Travel (eLOT) number.
              example: 365
            elotFlag:
              type: string
              description: eLOT Ascending/Descending Flag.
              example: D
            lacsLinkReturnCode:
              type: string
              description: LACSLink return code.
              example: 92
            lacsLinkIndicator:
              type: string
              description: LACSLink indicator.
              example: Y
              enum:
              - Y
              - N
              - F
              - S
              - blank
            poBoxOnlyPostalCode:
              type: boolean
              description: PO Box only postal code.
              example: false
            suitelinkFootnote:
              type: string
              description: Footnotes from matching a street or highrise record to suite information.
              example: 0
            pmbDesignator:
              type: string
              description: Private Mail Box unit designator.
              example: Piloto
            pmbNumber:
              type: string
              description: Private Mail Box number.
              example: 123
            addressRecordType:
              type: string
              description: Type of the address record that matches the input address.
              example: R
              enum:
              - F
              - G
              - H
              - P
              - R
              - S
            defaultAddress:
              type: boolean
              description: Indicator that a default address was found, but more specific addresses exists.
              example: false
            errorMessage:
              type: string
              description: Error message for USPS data retrieval.
              example: Invalid zip code extension
            cassProcessed:
              type: boolean
              description: Has the request been CASS processed.
              example: false
        englishLatinAddress:
          type: object
          description: The address translated to English.
          properties:
            formattedAddress:
              type: string
              description: The post-processed address, formatted as a single-line address.
              example: 123 Main St. New Orleans, LA 70112-2431, US
            postalAddress:
              type: object
              description: Represents a postal address, such as for postal delivery.
              properties:
                revision:
                  type: integer
                  description: The schema revision.
                  example: 0
                regionCode:
                  type: string
                  description: CLDR region code of the country/region of the address.
                  example: CH
                languageCode:
                  type: string
                  description: Two letter language code.
                  example: en
                postalCode:
                  type: string
                  description: Postal code of the address.
                  example: 90210
                sortingCode:
                  type: string
                  description: Additional, country-specific, sorting code.
                  example: CEDEX 7
                administrativeArea:
                  type: string
                  description: Highest administrative subdivision which is used for postal addresses of a country or region.
                  example: Barcelona
                locality:
                  type: string
                  description: Generally refers to the city or town portion of the address.
                  example: New York
                sublocality:
                  type: string
                  description: Neighborhood, borough, or district.
                  example: Brooklyn
                addressLines:
                  type: array
                  description: Unstructured address lines describing the lower levels of an address.
                  example:
                  - 123 Main St.
                  - New Orleans
                  - LA
                  - 70112-2431
                  - US
                  items:
                    type: string
            addressComponents:
              description: List of address components such as a street, city, or state.
              type: array
              items:
                type: object
                properties:
                  componentName:
                    type: object
                    description: A wrapper for the name of the component.
                    properties:
                      text:
                        type: string
                        description: The name text.
                        example: Main St.
                      languageCode:
                        type: string
                        description: Two letter language code.
                        example: en
                  componentType:
                    type: string
                    description: The type of the address component.
                    example: street_number
                  confirmationLevel:
                    type: string
                    description: Indicates the level of certainty that the component is correct.
                    example: CONFIRMED
                    enum:
                    - CONFIRMATION_LEVEL_UNSPECIFIED
                    - CONFIRMED
                    - UNCONFIRMED_BUT_PLAUSIBLE
                    - UNCONFIRMED_AND_SUSPICIOUS
            missingComponentTypes:
              description: The types of components that were expected to be present in a correctly formatted mailing address but were not found in the input AND could not be inferred.
              type: array
              example:
              - street_address
              - postal_code
              items:
                type: string
            unconfirmedComponentTypes:
              description: The types of the components that are present in the addressComponents but could not be confirmed to be correct.
              type: array
              example:
              - subpremise
              - route
              items:
                type: string
            unresolvedTokens:
              description: Input that was not recognized as a valid part of an address.
              type: array
              example:
              - Box
              - '11789'
              items:
                type: string
    ValidatedAddressMatch:
      $ref: '#/components/schemas/validated-address-match'
    ValidateAddress:
      $ref: '#/components/schemas/validate-address'
    internal-server-error:
      type: object
      summary: Internal Server Error
      description: Processing Error
      properties:
        code:
          description: Error code. Refer to the list of [Errors](/#tag/Errors).
          type: integer
        message:
          description: Error message explaining the code.
          type: string
        status:
          type: string
          enum:
          - error
          example: error
        errors:
          description: Displays processing error.
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            summary: Forbidden
            description: Error relating to insufficient permissions for a resource
            properties:
              code:
                description: Error code. Refer to the list of [Errors](/#tag/Errors).
                type: integer
              message:
                description: Error message explaining the code.
                type: string
              status:
                type: string
                enum:
                - error
                example: error
              errors:
                description: Displays processing error.
                type: array
                minItems: 1
                maxItems: 1
                items:
                  type: string
          examples:
            revoked:
              summary: Forbidden Authorization Revoked
              description: 'Forbidden: Authorization revoked'
              value:
                code: 1008
                message: 'Forbidden: Authorization revoked'
                errors:
                - 'Forbidden: Authorization revoked'
            scope:
              summary: Forbidden Scope
              description: 'Forbidden: Missing required scope'
              value:
                code: 1009
                message: 'Forbidden: Missing required scope'
                errors:
                - 'Forbidden: Missing required scope'
    rate-limit:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            summary: Too Many Requests
            description: Error for too many requests in a given time frame. See [Rate Limits](/#tag/RateLimit) for more information.
            properties:
              code:
                description: Error code. Refer to the list of [Errors](/#tag/Errors).
                type: integer
              message:
                description: Error message explaining the code.
                type: string
              status:
                type: string
                enum:
                - error
                example: error
              errors:
                description: Displays processing error.
                type: array
                minItems: 1
                maxItems: 1
                items:
                  type: string
          examples:
            rateLimit:
              summary: Too Many Requests
              description: Too many requests. Please wait before trying again.
              value:
                code: 1015
                message: Too many requests. Please wait before trying again.
                errors:
                - Too many requests. Please wait before trying again.
    payment-required:
      description: Payment Required
      content:
        application/json:
          schema:
            type: object
            summary: Payment Required
            description: There are insufficient funds available for this resource
            properties:
              code:
                description: Error code. Refer to the list of [Errors](/#tag/Errors).
                type: integer
              message:
                description: Error message explaining the code.
                type: string
              status:
                type: string
                enum:
                - error
                example: error
              errors:
                description: Duplicate of the error message
                type: array
                items:
                  type: string
          examples:
            paymentRequired:
              summary: Payment Required
              description: Insufficient funds
              value:
                code: 1080
                message: Insufficient funds
                errors:
                - Insufficient funds
    bad-request:
      type: object
      summary: Bad Request
      description: Validation error with the request
      properties:
        code:
          description: Error code. Refer to the list of [Errors](/#tag/Errors).
          type: integer
        message:
          description: Error message explaining the code.
          type: string
        status:
          type: string
          enum:
          - error
          example: error
        errors:
          description: Lists validation errors with the schema or the resource being operated on.
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: string
    Forbidden:
      $ref: '#/components/schemas/forbidden'
    InternalServerError:
      $ref: '#/components/schemas/internal-server-error'
    BadRequest:
      $ref: '#/components/schemas/bad-request'
    validate-address:
      type: object
      properties:
        street1:
          description: The street address.
          type: string
          maxLength: 50
          example: 113 INTL BROADWAY
        street2:
          description: Additional space for street address.
          type: string
          maxLength: 50
          example: ''
        city:
          type: string
          description: The city.
          example: LOS ANGELES
        province:
          type: string
          description: The province or the state. Optional. Required for US.
          example: CA
        postal_code:
          type: string
          description: The postal code or ZIP Code.
          example: '91013'
        country:
          type: string
          description: 'The country in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. Required.


            Allowed Values: AR, AT, AU, BE, BG, BR, CA, CH, CL, CO, CZ, DE, DK, EE, ES, FI, FR, GB, HR, HU, IE, IN, IT, JP, LT, LU, LV, MX, MY, NL, NO, NZ, PL, PR, PT, SE, SG, SI, SK, US'
          example: US
      required:
      - street1
      - city
      - country
      additionalProperties: false
    unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            summary: Unauthorized
            description: Lack of valid authentication credentials for the resource
            properties:
              code:
                description: Error code. Refer to the list of [Errors](/#tag/Errors).
                type: integer
              message:
                description: Error message explaining the code.
                type: string
              status:
                type: string
                enum:
                - error
                example: error
              errors:
                description: Displays processing error.
                type: array
                minItems: 1
                maxItems: 1
                items:
                  type: string
          examples:
            accessToken:
              summary: Invalid access token
              description: Invalid access token
              value:
                code: 1005
                message: Invalid access token
                errors:
                - Invalid access token
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    validated-address:
      type: object
      properties:
        original:
          type: object
          $ref: '#/components/schemas/ValidateAddress'
        error:
          type: boolean
          description: Whether or not there has been an error while validating the address.
          example: true
        message:
          type: string|null
          description: A message which explains the error occurred.
        matches:
          type: array
          description: List of postal address matches for the provided original address.
          items:
            $ref: '#/components/schemas/ValidatedAddressMatch'
      additionalProperties: false
    PaymentRequ

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boxc/refs/heads/main/openapi/boxc-validateaddress-api-openapi.yml