openapi: 3.1.0
info:
  title: Shippo Address API
  summary: The Shippo Address API
  description: >-
    Address book, Address validation, and Address parsing.
    [https://goshippo.com](https://goshippo.com/)
  x-logo:
    url: https://docs.goshippo.com/images/shippo-logo.svg
  contact:
    name: Shippo Support
    url: https://support.goshippo.com/hc
    email: support@shippo.zendesk.com
  version: '0.1'
servers:
  - url: https://api.goshippo.com
tags:
  - name: Address Book
    description: Store, retrieve, modify, and delete your address book contacts
  - name: Validation
    description: Check your address is valid before creating shipping labels
  - name: Parser
    description: Convert address strings into a correctly formatted address object
paths:
  /v2/addresses/validate:
    get:
      tags:
        - Validation
      summary: Validate address
      description: >-
        Returns validation test results along with a recommended address.
        Validates both US and international addresses.


        **US required combinations**


        - state_province + city_locality + address_line_1

        - or address_line_1 + postal_code


        **International required combinations**


        - city_locality + address_line_1
      operationId: validate_address_addresses_validate_get
      security:
        - Shippo_Token: []
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
            maxLength: 64
            description: The name of the addressee
            example: Wilson
            title: Name
          description: The name of the addressee
        - name: organization
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
            description: The organization of the addressee
            example: Shippo
            title: Organization
          description: The organization of the addressee
        - name: address_line_1
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 100
            description: The first line of the address
            example: 731 Market Street
            title: Address Line 1
          description: The first line of the address
        - name: address_line_2
          in: query
          required: false
          schema:
            type: string
            maxLength: 50
            description: >-
              The second line of the address. Must be percent encoded when
              passed as a query parameter (e.g. `#200` → `%23200`).
            example: '#200'
            title: Address Line 2
          description: >-
            The second line of the address. Must be percent encoded when passed
            as a query parameter (e.g. `#200` → `%23200`).
        - name: city_locality
          in: query
          required: false
          schema:
            type: string
            maxLength: 64
            description: The city or locality of the address
            example: San Francisco
            title: City Locality
          description: The city or locality of the address
        - name: state_province
          in: query
          required: false
          schema:
            type: string
            maxLength: 32
            description: The state, province, county, or municipal division
            example: CA
            title: State Province
          description: The state, province, county, or municipal division
        - name: postal_code
          in: query
          required: false
          schema:
            type: string
            maxLength: 16
            description: The postal code or zip code
            example: '94103'
            title: Postal Code
          description: The postal code or zip code
        - name: country_code
          in: query
          required: true
          schema:
            allOf:
              - $ref: '#/components/schemas/CountryCodeISO2'
            description: The ISO 3166 country code
            example: US
            title: Country Code
          description: The ISO 3166 country code
      x-codeSamples:
        - lang: cURL
          label: curl
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/addresses/validate?name=Wilson&organization=Shippo&address_line_1=731%20Market%20Street&address_line_2=%23200&city_locality=San%20Francisco&state_province=CA&postal_code=94103&country_code=US'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '422':
          content:
            application/json:
              example:
                detail:
                  - type: string_too_short
                    loc:
                      - query
                      - address_line_1
                    msg: String should have at least 1 character
                    input: ''
                    ctx:
                      min_length: 1
                    url: https://errors.pydantic.dev/2.3/v/string_too_short
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
  /v2/addresses/parse:
    get:
      tags:
        - Parser
      summary: Parse Address
      description: Parses a single string into an Address model
      operationId: parse_address_addresses_parse_get
      security:
        - Shippo_Token: []
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
            example: >-
              Shippo 731 Market St #200, San Francisco, CA 94103 US
              shippo@shippo.com +1-555-999-8888
            title: Address
      x-codeSamples:
        - lang: cURL
          label: curl
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/addresses/parse?address=Shippo%20731%20Market%20St%20%23200%2C%20San%20Francisco%2C%20CA%2094103%20US%20shippo%40shippo.com%20%2B1-555-999-8888'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressParseResponse'
        '422':
          content:
            application/json:
              example:
                detail:
                  - type: missing
                    loc:
                      - query
                      - address
                    msg: Field required
                    input: null
                    url: https://errors.pydantic.dev/2.3/v/missing
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
  /v2/addresses/{address_id}:
    get:
      tags:
        - Address Book
      summary: Retrieve a single address
      description: Returns an existing address using an object ID
      operationId: get_one_address_addresses__address_id__get
      security:
        - Shippo_Token: []
      parameters:
        - name: address_id
          in: path
          required: true
          schema:
            type: string
            title: Address Id
      x-codeSamples:
        - lang: cURL
          label: curl
          source: |-
            curl -i -X GET \
            'https://api.goshippo.com/v2/addresses/{address_id}' \
            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressWithMetadata'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
    put:
      tags:
        - Address Book
      summary: Update an address
      description: Updates values in an existing address
      operationId: update_an_address_addresses__address_id__put
      security:
        - Shippo_Token: []
      parameters:
        - name: address_id
          in: path
          required: true
          schema:
            type: string
            title: Address Id
      x-codeSamples:
        - lang: cURL
          label: curl
          source: |-
            curl -i -X PUT \
            'https://api.goshippo.com/v2/addresses/{address_id}' \
            -H 'Authorization: ShippoToken <API_TOKEN>' \
            -H 'Content-Type: application/json' \
            -d '{
              "name": "Wilson",
              "organization": "Shippo",
              "email": "user@shippo.com",
              "phone": "+1-4155550132",
              "address_line_1": "731 Market Street",
              "address_line_2": "#200",
              "city_locality": "San Francisco",
              "state_province": "CA",
              "postal_code": "94103",
              "country_code": "US",
              "address_type": "residential"
            }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequest'
      responses:
        '204':
          description: Successful Response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                anyOf:
                  - properties:
                      detail:
                        default: Duplicate Address
                        examples:
                          - Duplicate Address
                        title: Detail
                        type: string
                    title: DuplicateAddressResponse
                    type: object
                  - properties:
                      detail:
                        default: Concurrent Write Conflict
                        examples:
                          - Concurrent Write Conflict
                        title: Detail
                        type: string
                    title: ConcurrentWriteConflictResponse
                    type: object
              examples:
                Duplicate address:
                  value:
                    detail: Duplicate Address
                Concurrent write conflict:
                  value:
                    detail: Concurrent Write Conflict
          description: Conflict
        '422':
          content:
            application/json:
              example:
                detail:
                  - type: enum
                    loc:
                      - body
                      - address_type
                    msg: Input should be 'unknown','residential' or 'commercial'
                    input: business
                    ctx:
                      expected: '''unknown'',''residential'' or ''commercial'''
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
    delete:
      tags:
        - Address Book
      summary: Delete an address
      description: Removes an existing address from your address book using an object ID
      operationId: delete_an_address_addresses__address_id__delete
      security:
        - Shippo_Token: []
      parameters:
        - name: address_id
          in: path
          required: true
          schema:
            type: string
            title: Address Id
      x-codeSamples:
        - lang: cURL
          label: curl
          source: |-
            curl -i -X DELETE \
            'https://api.goshippo.com/v2/addresses/{address_id}' \
            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '204':
          description: Successful Response
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConcurrentWriteConflictResponse'
          description: Conflict
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
  /v2/addresses:
    post:
      tags:
        - Address Book
      summary: Create a new address
      description: Stores a new address to your address book
      operationId: create_a_new_address_addresses_post
      security:
        - Shippo_Token: []
      parameters: []
      x-codeSamples:
        - lang: cURL
          label: curl
          source: |-
            curl -i -X POST \
            https://api.goshippo.com/v2/addresses \
            -H 'Authorization: ShippoToken <API_TOKEN>' \
            -H 'Content-Type: application/json' \
            -d '{
              "name": "Wilson",
              "organization": "Shippo",
              "email": "user@shippo.com",
              "phone": "+1-4155550132",
              "address_line_1": "731 Market Street",
              "address_line_2": "#200",
              "city_locality": "San Francisco",
              "state_province": "CA",
              "postal_code": "94103",
              "country_code": "US",
              "address_type": "residential"
            }'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AddressWithMetadata'
                  - type: object
                title: Response Create A New Address Addresses Post
        '409':
          content:
            application/json:
              schema:
                anyOf:
                  - properties:
                      detail:
                        default: Duplicate Address
                        examples:
                          - Duplicate Address
                        title: Detail
                        type: string
                    title: DuplicateAddressResponse
                    type: object
                  - properties:
                      detail:
                        default: Exceeded maximum of 3000 records in address book
                        examples:
                          - Exceeded maximum of 3000 records in address book
                        title: Detail
                        type: string
                    title: ExceededMaximumRecords
                    type: object
              examples:
                Duplicate address:
                  value:
                    detail: Duplicate Address
                Exceeded maximum of 3000 records in address book:
                  value:
                    detail: Exceeded maximum of 3000 records in address book
          description: Conflict
        '422':
          content:
            application/json:
              example:
                detail:
                  - type: missing
                    loc:
                      - body
                      - name
                    msg: Field required
                    input:
                      email: user@shippo.com
                      phone: +1-4155550132
                      organization: Shippo
                      address_line_1: 731 Market Street
                      state_province: CA
                      postal_code: '410'
                      country_code: US
                      address_type: residential
                    url: https://errors.pydantic.dev/2.3/v/missing
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequest'
    get:
      tags:
        - Address Book
      summary: Retrieve addresses
      description: Returns a list of addresses based on search criteria
      operationId: get_addresses_addresses_get
      security:
        - Shippo_Token: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            title: Offset
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 30
            title: Limit
        - name: search
          in: query
          required: false
          schema:
            type: string
            title: Search
      x-codeSamples:
        - lang: cURL
          label: curl
          source: >-
            curl -i -X GET \

            'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string'
            \

            -H 'Authorization: ShippoToken <API_TOKEN>'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressesResponse'
        '422':
          content:
            application/json:
              example:
                detail:
                  - type: greater_than_equal
                    loc:
                      - query
                      - limit
                    msg: Input should be greater than or equal to 1
                    input: '0'
                    ctx:
                      ge: 1
                    url: https://errors.pydantic.dev/2.3/v/greater_than_equal
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        5XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
          description: Server Error
components:
  schemas:
    Address:
      properties:
        name:
          type: string
          title: Name
          example: Wilson
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          example: user@shippo.com
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          example: +1-4155550132
        organization:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization
          example: Shippo
        address_line_1:
          type: string
          title: Address Line 1
          example: 731 Market Street
        address_line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 2
          example: '#200'
        city_locality:
          anyOf:
            - type: string
            - type: 'null'
          title: City Locality
          example: San Francisco
        state_province:
          anyOf:
            - type: string
            - type: 'null'
          title: State Province
          example: CA
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
          example: '94103'
        country_code:
          type: string
          title: Country Code
          example: US
        address_type:
          allOf:
            - $ref: '#/components/schemas/AddressType'
          default: unknown
          example: residential
      type: object
      required:
        - name
        - address_line_1
        - country_code
      title: Address
    AddressAttributes:
      type: string
      enum:
        - address_line_1
        - address_line_2
        - city_locality
        - state_province
        - postal_code
        - country_code
      title: AddressAttributes
    AddressParseResponse:
      properties:
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          example: user@shippo.com
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          example: +1-4155550132
        address_line_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 1
          example: 731 Market Street
        address_line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 2
          example: '#200'
        city_locality:
          anyOf:
            - type: string
            - type: 'null'
          title: City Locality
          example: San Francisco
        state_province:
          anyOf:
            - type: string
            - type: 'null'
          title: State Province
          example: CA
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
          example: '94103'
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          example: US
      type: object
      title: AddressParseResponse
      description: The parsed response of an address.
    AddressRequest:
      properties:
        name:
          type: string
          maxLength: 64
          title: Name
          description: The name of the addressee
          example: Wilson
        organization:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Organization
          description: The organization of the addressee
          example: Shippo
        email:
          anyOf:
            - type: string
              maxLength: 128
              minLength: 5
              format: email
            - type: 'null'
          title: Email
          description: The email of the addressee
          example: user@shippo.com
        phone:
          anyOf:
            - type: string
              maxLength: 32
              minLength: 3
            - type: 'null'
          title: Phone
          description: The phone number of the addressee
          example: +1-4155550132
        address_line_1:
          type: string
          maxLength: 100
          minLength: 1
          title: Address Line 1
          description: The first line of the address
          example: 731 Market Street
        address_line_2:
          anyOf:
            - type: string
              maxLength: 50
            - type: 'null'
          title: Address Line 2
          description: >-
            The second line of the address. Must be percent encoded when passed
            as a query parameter (e.g. `#200` → `%23200`).
          example: '#200'
        city_locality:
          anyOf:
            - type: string
              maxLength: 64
            - type: 'null'
          title: City Locality
          description: The city or locality of the address
          example: San Francisco
        state_province:
          anyOf:
            - type: string
              maxLength: 32
            - type: 'null'
          title: State Province
          description: The state, province, county, or municipal division
          example: CA
        postal_code:
          anyOf:
            - type: string
              maxLength: 16
            - type: 'null'
          type: string
          title: Postal Code
          description: The postal code or zip code
          example: '94103'
        country_code:
          type: string
          maxLength: 2
          minLength: 2
          title: Country Code
          description: The ISO 3166 country code
          example: US
        address_type:
          allOf:
            - $ref: '#/components/schemas/AddressType'
          description: >-
            The category of the address. It may affect how certain carriers
            charge for a delivery/pickup.It is recommended to specify it, if it
            is known.
          default: unknown
          example: residential
      type: object
      required:
        - name
        - address_line_1
        - country_code
      title: AddressRequest
    AddressType:
      type: string
      enum:
        - unknown
        - residential
        - commercial
        - po_box
        - military
      title: AddressType
      description: >-
        The residential/commercial type of the address from the delivery/pickup
        standpoint


        `unknown` At the moment it is not possible to establish if the address
        is of any known type


        `residential` The address is a residence


        `commercial` The address is associated with a business


        `po_box` The address is a PO Box


        `military` The address is a military address
    AddressWithMetadata:
      properties:
        id:
          type: string
          title: Id
          example: e9f1f6fd20f84982afe471ff06c5a80f
        address:
          $ref: '#/components/schemas/Address'
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - address
        - updated_at
        - created_at
      title: AddressWithMetadata
    AddressesResponse:
      properties:
        offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Offset
          example: 1
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
          example: 1
        count:
          type: integer
          title: Count
          example: 1
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
          example: /addresses?offset=2&limit=1
        prev:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev
          example: /addresses?offset=0&limit=1
        results:
          items:
            $ref: '#/components/schemas/AddressWithMetadata'
          type: array
          title: Results
      type: object
      required:
        - count
        - results
      title: AddressesResponse
    Analysis:
      properties:
        validation_result:
          oneOf:
            - $ref: '#/components/schemas/ResultValid'
            - $ref: '#/components/schemas/ResultPartiallyValid'
            - $ref: '#/components/schemas/ResultInvalid'
          title: Validation Result
          discriminator:
            propertyName: value
            mapping:
              invalid: '#/components/schemas/ResultInvalid'
              partially_valid: '#/components/schemas/ResultPartiallyValid'
              valid: '#/components/schemas/ResultValid'
        address_type:
          allOf:
            - $ref: '#/components/schemas/AddressType'
          default: unknown
        changed_attributes:
          anyOf:
            - items:
                $ref: '#/components/schemas/AddressAttributes'
              type: array
              uniqueItems: true
            - type: 'null'
          title: Changed Attributes
      type: object
      required:
        - validation_result
      title: Analysis
    AutocompleteAddressResponse:
      properties:
        offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Offset
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
        count:
          type: integer
          title: Count
        next:
          anyOf:
            - type: string
            - type: 'null'
          title: Next
        prev:
          anyOf:
            - type: string
            - type: 'null'
          title: Prev
        results:
          items:
            $ref: '#/components/schemas/AutocompletedAddress'
          type: array
          title: Results
      type: object
      required:
        - count
        - results
      title: AutocompleteAddressResponse
    AutocompleteFindAddressType:
      type: string
      enum:
        - address
        - container
      title: AutocompleteFindAddressType
      description: >-
        The type of address autocompletion result.


        `Address` This item implies a single address.


        `Container` This item is not a valid address but collection of
        addresses. i.e. a reference to a street or a

        building.
    AutocompletedAddress:
      properties:
        id:
          type: string
          title: Id
        address:
          type: string
          title: Address
        type:
          $ref: '#/components/schemas/AutocompleteFindAddressType'
      type: object
      required:
        - id
        - address
        - type
      title: AutocompletedAddress
    ConcurrentWriteConflictResponse:
      properties:
        detail:
          type: string
          title: Detail
          default: Concurrent Write Conflict
          examples:
            - Concurrent Write Conflict
      type: object
      title: ConcurrentWriteConflictResponse
    ConfidenceHigh:
      properties:
        score:
          type: string
          enum:
            - high
          const: high
          title: Score
          default: high
        code:
          type: string
          title: Code
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - code
      title: ConfidenceHigh
    ConfidenceLow:
      properties:
        score:
          type: string
          enum:
            - low
          const: low
          title: Score
          default: low
        code:
          type: string
          title: Code
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - code
      title: ConfidenceLow
    ConfidenceMedium:
      properties:
        score:
          type: string
          enum:
            - medium
          const: medium
          title: Score
          default: medium
        code:
          type: string
          title: Code
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - code
      title: ConfidenceMedium
    CountryCodeISO2:
      type: string
      enum:
        - AE
        - AR
        - AT
        - AU
        - AX
        - AZ
        - BA
        - BD
        - BE
        - BG
        - BH
        - BM
        - BN
        - BR
        - BS
        - BW
        - BY
        - CA
        - CH
        - CL
        - CO
        - CN
        - CY
        - CZ
        - DE
        - DK
        - EC
        - EE
        - EG
        - ES
        - FI
        - FO
        - FR
        - GB
        - GE
        - GF
        - GG
        - GI
        - GP
        - GR
        - GU
        - HK
        - HR
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IS
        - IT
        - JE
        - JO
        - JP
        - KR
        - KY
        - KW
        - KZ
        - LB
        - LI
        - LT
        - LU
        - LV
        - MA
        - MC
        - MD
        - ME
        - MK
        - MO
        - MP
        - MQ
        - MT
        - MX
        - MY
        - NA
        - NL
        - 'NO'
        - NZ
        - OM
        - PE
        - PH
        - PL
        - PM
        - PR
        - PT
        - PY
        - QA
        - RE
        - RO
        - RU
        - SA
        - SC
        - SE
        - SG
        - SI
        - SK
        - SM
        - SR
        - TH
        - TN
        - TR
        - TW
        - UA
        - US
        - UY
        - VN
        - WE
        - YT
        - ZA
      title: CountryCodeISO2
      description: ISO2 country codes
    ErrorDetail:
      properties:
        type:
          type: string
          title: Type
          description: The type of error
          examples:
            - missing
        loc:
          items:
            type: string
          type: array
          title: Loc
          description: The location of the error
          examples:
            - - query
              - country_code
        msg:
          type: string
          title: Msg
          description: The error message
          examples:
            - Field required
        input:
          anyOf:
            - {}
            - type: 'null'
          title: Input
          description: The input values for this field
          examples:
            - 'null'
      type: object
      required:
        - type
        - loc
        - msg
      title: ErrorDetail
    Geo:
      properties:
        latitude:
          type: number
          title: Latitude
        longitude:
          type: number
          title: Longitude
      type: object
      required:
        - latitude
        - longitude
      title: Geo
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InternalServerErrorResponse:
      properties:
        message:
          type: string
          title: Message
          description: The error message for an internal server error
          default: Internal Server Error
        trace_id:
          type: string
          title: Trace Id
          description: >-
            The OpenTelemetry trace identifier that is unique to the request. A
            valid trace identifier is a 16-byte array with at least one non-zero
            byte
          example: b562cab2e9200ac3e11474cc877580e1
      type: object
      required:
        - trace_id
      title: InternalServerErrorResponse
    InvalidReason:
      properties:
        code:
          $ref: '#/components/schemas/InvalidReasonCode'
        type:
          $ref: '#/components/schemas/ReasonType'
        description:
          type: string
          title: Description
      type: object
      required:
        - code
        - type
        - description
      title: InvalidReason
    InvalidReasonCode:
      type: string
      enum:
        - address_vacant
        - address_not_found
        - address_found_non_postal_match
        - address_confirmed_missing_secondary
        - address_abbreviation_fixed
        - zip_post_code_not_found
        - zip_post_code_corrected
        - zip_plus_four_not_found
        - multiple_address_same_zip_post_code
        - incomplete_address_input
        - multiple_zip_plus_four_found
        - address_invalid_street_delivery
        - address_premise_invalid
        - address_confirmed_invalid_secondary
        - address_suffix_direction_not_found
        - address_street_not_found
        - address_incomplete_for_geocode
        - address_premise_missing
        - geocode_not_found
      title: InvalidReasonCode
      description: >-
        Value descriptions:     


        `address_vacant`: Address has been marked as vacant by the postal
        authority after 90 days of inactivity.        


        `address_not_found`: Address is not present in the database     


        `address_found_non_postal_match`: The address was confirmed using
        non-postal data sources.      


        `address_confirmed_missing_secondary`: The main address is present in
        the database, but it is missing secondary information (apartment, suite,
        etc.).    


        `address_abbreviation_fixed`: Address inputted was standardized for
        abbreviations according to postal authority rules.  


        `zip_post_code_not_found`: The ZIP Code in the submitted address could
        not be found because neither a valid city and state, nor valid 5-digit
        ZIP Code was present.     


        `zip_post_code_corrected`: The zip code has been corrected to a
        different ZIP Code.     


        `zip_plus_four_not_found`: This address is not present in the database
        for the provided zip code.       


        `multiple_address_same_zip_post_code`: Multiple addresses were returned,
        with the same ZIP code.        


        `incomplete_address_input`: The submitted address did not contain
        sufficiently complete or correct data to determine a single ZIP+4
        Code.        


        `multiple_zip_plus_four_found`: More than one ZIP+4 Code was found to
        satisfy the address as submitted. 


        `address_invalid_street_delivery`: The postal authority does not provide
        street delivery service for this ZIP Code.     


        `address_premise_invalid`: The premise (house or building) number for
        the address is not valid. 


        `address_confirmed_invalid_secondary`: The main address is present in
        the database, but the submitted secondary information (apartment, suite,
        etc.) was not recognized.        


        `address_suffix_direction_not_found`: The combination of directionals
        (N, E, SW, etc) and the suffix (AVE, ST, BLVD) is not correct and
        produced multiple possible matches.     


        `address_street_not_found`: Could not match the input street to a unique
        street name.   


        `address_incomplete_for_geocode`: The input address did not provide
        enough valid information to append a geocode.       


        `address_premise_missing`: The premise (house or building) number for
        the address is missing in the input.      


        `geocode_not_found`: Geocode could not be appended for the input
        locality or postal code.
    NotFoundResponse:
      properties:
        detail:
          type: string
          title: Detail
          default: Not Found
          examples:
            - Not Found
      type: object
      title: NotFoundResponse
    OriginalAddress:
      properties:
        address_line_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 1
        address_line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 2
        city_locality:
          anyOf:
            - type: string
            - type: 'null'
          title: City Locality
        state_province:
          anyOf:
            - type: string
            - type: 'null'
          title: State Province
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        organization:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
      type: object
      title: OriginalAddress
    PartiallyValidReason:
      properties:
        code:
          $ref: '#/components/schemas/PartiallyValidReasonCode'
        type:
          $ref: '#/components/schemas/ReasonType'
        description:
          type: string
          title: Description
      type: object
      required:
        - code
        - type
        - description
      title: PartiallyValidReason
    PartiallyValidReasonCode:
      type: string
      enum:
        - address_found
        - address_vacant
        - address_confirmed_missing_secondary
        - address_confirmed_invalid_secondary
        - address_found_non_postal_match
        - alternate_address_found
        - military_zip_found
        - address_lacslink_true
        - zip_post_code_corrected
        - city_state_corrected
        - address_used_name_org
        - dual_address_found
        - address_found_direction_change
        - address_found_suffix_modified
        - street_name_corrected
        - address_abbreviation_fixed
        - city_name_corrected
        - zip_plus_four_corrected
        - unique_zip_post_code_found
        - city_state_not_found
        - multiple_address_same_zip_post_code
        - multiple_zip_plus_four_found
        - address_organization_corrected
        - address_premise_info_corrected
        - address_premise_type_corrected
        - address_secondary_info_corrected
        - address_secondary_type_corrected
        - street_direction_corrected
        - street_component_corrected
        - city_locality_corrected
        - state_province_corrected
      title: PartiallyValidReasonCode
      description: >-
        Value descriptions:     


        `address_found`: The entire address is present in the database. 


        `address_vacant`: Address has been marked as vacant by the postal
        authority after 90 days of inactivity.        


        `address_confirmed_missing_secondary`: The main address is present in
        the database, but it is missing secondary information (apartment, suite,
        etc.).   


        `address_confirmed_invalid_secondary`: The main address is present in
        the database, but the submitted secondary information (apartment, suite,
        etc.) was not recognized.        


        `address_found_non_postal_match`: The address was confirmed using
        non-postal data sources.      


        `alternate_address_found`: An alternate/better address has been found in
        the database.  


        `military_zip_found`: The address has a military/diplomatic zip code.   


        `address_lacslink_true`: The inputted address was found with the LACS
        Link indicator set as true.       


        `zip_post_code_corrected`: The zip code has been corrected to a
        different ZIP Code.     


        `city_state_corrected`: The spelling of the city name and/or state
        abbreviation has been corrected to the standard spelling.    


        `address_used_name_org`: Information in the name or organization input
        field was determined to be part of the address.  


        `dual_address_found`: The inputted address contained two addresses.     


        `address_found_direction_change`: Address found by changing the cardinal
        direction (North, South, East, West).  


        `address_found_suffix_modified`: An address component (i.e., directional
        or suffix only) was added, changed, or deleted in order to achieve a
        match.    


        `street_name_corrected`: Address found by correcting the spelling of the
        street name.   


        `address_abbreviation_fixed`: Address inputted was standardized for
        abbreviations according to postal authority rules.  


        `city_name_corrected`: The city name in the submitted address has been
        corrected according to postal authority rules.   


        `zip_plus_four_corrected`: The zip plus four in the submitted address
        has been moved to a new zip code. 


        `unique_zip_post_code_found`: The address has a unique zip code.        


        `city_state_not_found`: The city and state in the submitted address
        could not be verified as corresponding to the given ZIP Code.       


        `multiple_address_same_zip_post_code`: Multiple addresses were returned,
        with the same ZIP code.        


        `multiple_zip_plus_four_found`: More than one ZIP+4 Code was found to
        satisfy the address as submitted. 


        `address_organization_corrected`: Address found by correcting the
        organization name inputted.   


        `address_premise_info_corrected`: Address found by correcting the
        premise information inputted. 


        `address_premise_type_corrected`: Address found by correcting the type
        of premise inputted.     


        `address_secondary_info_corrected`: Address found by correcting the
        secondary information inputted.     


        `address_secondary_type_corrected`: Address found by correcting the type
        of secondary information inputted (from "Apt" to "Ste").       


        `street_direction_corrected`: Address found by correcting the street
        pre/post directional (from "W" to "E").    


        `street_component_corrected`: Address found by correcting the street
        leading or trailing type (from "Rd" to "Ave").     


        `city_locality_corrected`: The city/locality has been corrected.        


        `state_province_corrected`: The state/province has been corrected.
    ReasonType:
      type: string
      enum:
        - info
        - warning
        - correction
        - error
      title: ReasonType
    RecommendedAddress:
      properties:
        address_line_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 1
        address_line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 2
        city_locality:
          anyOf:
            - type: string
            - type: 'null'
          title: City Locality
        state_province:
          anyOf:
            - type: string
            - type: 'null'
          title: State Province
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        organization:
          anyOf:
            - type: string
            - type: 'null'
          title: Organization
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
        complete_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Complete Address
        confidence_result:
          oneOf:
            - $ref: '#/components/schemas/ConfidenceHigh'
            - $ref: '#/components/schemas/ConfidenceMedium'
            - $ref: '#/components/schemas/ConfidenceLow'
          title: Confidence Result
          discriminator:
            propertyName: score
            mapping:
              high: '#/components/schemas/ConfidenceHigh'
              low: '#/components/schemas/ConfidenceLow'
              medium: '#/components/schemas/ConfidenceMedium'
      type: object
      required:
        - confidence_result
      title: RecommendedAddress
      description: >-
        The recommended address is an address we recommend the consumer to use.
        The attributes have less constraints

        all values may be NoneType
    ResultInvalid:
      properties:
        value:
          const: invalid
          title: Value
          default: invalid
        reasons:
          items:
            $ref: '#/components/schemas/InvalidReason'
          type: array
          uniqueItems: true
          title: Reasons
          default: []
      type: object
      title: ResultInvalid
    ResultPartiallyValid:
      properties:
        value:
          const: partially_valid
          title: Value
          default: partially_valid
        reasons:
          items:
            $ref: '#/components/schemas/PartiallyValidReason'
          type: array
          uniqueItems: true
          title: Reasons
          default: []
      type: object
      title: ResultPartiallyValid
    ResultValid:
      properties:
        value:
          const: valid
          title: Value
          default: valid
        reasons:
          items:
            $ref: '#/components/schemas/ValidReason'
          type: array
          uniqueItems: true
          title: Reasons
          default: []
      type: object
      title: ResultValid
    RetrieveAddressResponse:
      properties:
        address_line_1:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 1
          example: 731 Market Street
        address_line_2:
          anyOf:
            - type: string
            - type: 'null'
          title: Address Line 2
          example: '#200'
        city_locality:
          anyOf:
            - type: string
            - type: 'null'
          title: City Locality
          example: San Francisco
        state_province:
          anyOf:
            - type: string
            - type: 'null'
          title: State Province
          example: CA
        postal_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Postal Code
          example: '94103'
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          example: US
      type: object
      title: RetrieveAddressResponse
    UnprocessableEntityResponse:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
          title: Detail
          description: Details of the issue with the request.
      type: object
      required:
        - detail
      title: UnprocessableEntityResponse
      description: A response for invalid requests with details of the issue.
    ValidReason:
      properties:
        code:
          $ref: '#/components/schemas/ValidReasonCode'
        type:
          $ref: '#/components/schemas/ReasonType'
        description:
          type: string
          title: Description
      type: object
      required:
        - code
        - type
        - description
      title: ValidReason
    ValidReasonCode:
      type: string
      enum:
        - address_vacant
        - address_found
        - address_found_non_postal_match
        - alternate_address_found
        - unique_zip_post_code_found
        - military_zip_found
        - address_lacslink_true
      title: ValidReasonCode
      description: >-
        Value descriptions:     


        `address_vacant`: Address has been marked as vacant by the postal
        authority after 90 days of inactivity.        


        `address_found`: The entire address is present in the database. 


        `address_found_non_postal_match`: The address was confirmed using
        non-postal data sources.      


        `alternate_address_found`: An alternate/better address has been found in
        the database.  


        `unique_zip_post_code_found`: The address has a unique zip code.        


        `military_zip_found`: The address has a military/diplomatic zip code.   


        `address_lacslink_true`: The inputted address was found with the LACS
        Link indicator set as true.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ValidationResponse:
      properties:
        original_address:
          $ref: '#/components/schemas/OriginalAddress'
        recommended_address:
          anyOf:
            - $ref: '#/components/schemas/RecommendedAddress'
            - type: 'null'
        analysis:
          $ref: '#/components/schemas/Analysis'
        geo:
          anyOf:
            - $ref: '#/components/schemas/Geo'
            - type: 'null'
      type: object
      required:
        - original_address
        - analysis
      title: ValidationResponse
  securitySchemes:
    Shippo_Token:
      type: apiKey
      description: |

        Enter your shippo token with the ShippoToken prefix.

        Example: `ShippoToken shippo_live_xxxx`
      in: header
      name: Authorization
      x-default: 'ShippoToken '