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

# Save an address

> Saves a US address for your company and returns it, for new programs to use as their `addressId`. A prepaid Visa card program's address is the billing address on its cards.

The key's owner must be an admin who is allowed to create programs.


* **Safe to repeat.** Saving an address your company already has returns the saved one instead of a copy. Case and spacing don't matter, and a state's code counts the same as its name.
* **US only**, as in the dashboard. Send the state as its two-letter code or its name; Hoppier stores the name.
* **The oldest address is the default.** New programs use it when you leave out `addressId`. Saving another address doesn't change the default.
* **At most 50** saved addresses per company.
* **Not in the API:** changing or deleting an address. Use the dashboard.


## OpenAPI

````yaml /openapi.yaml post /addresses
openapi: 3.1.0
info:
  title: Hoppier API
  version: 1.0.0-beta
  summary: Create and read your Hoppier programs, and add and list the people in them.
  description: >
    The Hoppier API is in **closed beta**. Everything in this reference runs in
    production today.


    - A full-access admin creates company API keys in the dashboard, under
    **Developers › API keys**. For a personal key, email
    [support@hoppier.com](mailto:support@hoppier.com).

    - There is no sandbox. Every key works against your live account.

    - We add fields and error codes without notice, so ignore anything you don't
    recognise. We don't rename or remove a documented field without announcing
    it on the [changelog](https://docs.hoppier.com/changelog) first.
  termsOfService: https://www.hoppier.com/terms
  contact:
    name: Hoppier support
    email: support@hoppier.com
servers:
  - url: https://app.hoppier.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Account
    description: Check an API key and see which account it belongs to.
  - name: Addresses
    description: Save and list your company's addresses, for new programs.
  - name: Merchants
    description: Look up the merchants and gift-card brands a program can allow.
  - name: Programs
    description: Read and create the reward programs in your account.
  - name: Participants
    description: Add people to a program and list them.
paths:
  /addresses:
    post:
      tags:
        - Addresses
      summary: Save an address
      description: >
        Saves a US address for your company and returns it, for new programs to
        use as their `addressId`. A prepaid Visa card program's address is the
        billing address on its cards.


        The key's owner must be an admin who is allowed to create programs.
      operationId: createAddress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAddressRequest'
            example:
              line1: 350 Fifth Avenue
              line2: Floor 20
              city: New York
              state: NY
              postalCode: '10118'
      responses:
        '200':
          description: >-
            The address: the new one, or the saved one if your company already
            had it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
              example:
                id: ad_7Ym2p0Lx3Q
                object: address
                line1: 350 Fifth Avenue
                line2: Floor 20
                city: New York
                state: New York
                postalCode: '10118'
                country: US
                isDefault: true
        '400':
          description: >
            `invalid_request`: a field is missing or invalid. `message` names
            the field; for the state, `parameter` is `state`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unknownState:
                  summary: A state Hoppier doesn't know
                  value:
                    error: invalid_request
                    message: >-
                      state must be a US state or territory, by its two-letter
                      code or its name.
                    parameter: state
                badPostalCode:
                  summary: Not a US ZIP code
                  value:
                    error: invalid_request
                    message: >-
                      "postalCode" must be a US ZIP code, such as 94105 or
                      94105-1234
                notUs:
                  summary: An address outside the US
                  value:
                    error: invalid_request
                    message: '"country" must be US: only US addresses can be saved'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >
            `insufficient_permission`: the key's owner isn't an admin of the
            company, or their role doesn't allow creating programs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notAdmin:
                  summary: The key's owner isn't an admin
                  value:
                    error: insufficient_permission
                    message: This API key's user is not an admin of this account.
                notAllowed:
                  summary: The key's owner can't create programs
                  value:
                    error: insufficient_permission
                    message: >-
                      This API key's user is not allowed to create programs, so
                      cannot save addresses.
        '409':
          description: >
            `address_limit_reached`: your company already has 50 saved
            addresses. Use one of them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: address_limit_reached
                message: This account already has 50 saved addresses.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: >
            `rate_limit_unavailable`: Hoppier couldn't check your rate limit, so
            nothing was saved. Retry after the number of seconds in
            `Retry-After`.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: rate_limit_unavailable
                message: Please retry shortly.
components:
  schemas:
    CreateAddressRequest:
      type: object
      required:
        - line1
        - city
        - state
        - postalCode
      properties:
        line1:
          type: string
          minLength: 4
          maxLength: 255
          examples:
            - 350 Fifth Avenue
        line2:
          type: string
          maxLength: 255
          examples:
            - Floor 20
        city:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - New York
        state:
          type: string
          description: >
            A US state or territory, by its two-letter code (`NY`) or its name
            (`New York`), in any case. The District of Columbia, Puerto Rico,
            Guam, the US Virgin Islands, American Samoa and the Northern Mariana
            Islands are included.
          examples:
            - NY
        postalCode:
          type: string
          pattern: ^\d{5}(-\d{4})?$
          description: A US ZIP code, five digits or ZIP+4.
          examples:
            - '10118'
        country:
          type: string
          enum:
            - US
          default: US
          description: Only US addresses can be saved.
    Address:
      type: object
      description: One of your company's saved addresses.
      required:
        - id
        - object
        - line1
        - city
        - state
        - postalCode
        - country
        - isDefault
      properties:
        id:
          type: string
          description: The address's id. Starts with `ad_`.
          examples:
            - ad_7Ym2p0Lx3Q
        object:
          type: string
          const: address
        line1:
          type: string
          examples:
            - 350 Fifth Avenue
        line2:
          type: string
          description: Left out when the address has no second line.
          examples:
            - Floor 20
        city:
          type: string
          examples:
            - New York
        state:
          type: string
          description: The state or territory's name.
          examples:
            - New York
        postalCode:
          type: string
          examples:
            - '10118'
        country:
          type: string
          description: Two-letter country code.
          examples:
            - US
        isDefault:
          type: boolean
          description: >
            `true` for the address new programs use when you leave out
            `addressId`: your company's oldest saved address.
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: >
            A machine-readable code, such as `unauthorized` or
            `program_not_found`. Act on it and the HTTP status. New codes can
            appear, so handle one you don't recognise by its status. [Every
            code](/guides/errors-and-rate-limits#error-codes).
          examples:
            - program_not_found
        message:
          type: string
          description: What went wrong, in plain words. Don't parse it; it can change.
          examples:
            - Program not found.
        parameter:
          type: string
          description: On some `invalid_request` errors, the field that was refused.
          examples:
            - email
  responses:
    Unauthorized:
      description: >
        `unauthorized`: the API key is missing or malformed, or it's wrong,
        unknown or switched off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingKey:
              summary: No API key
              value:
                error: unauthorized
                message: 'API key is missing. Send it as "Authorization: Bearer <key>".'
            invalidKey:
              summary: Malformed, wrong or unknown key
              value:
                error: unauthorized
                message: API key is not valid.
            inactiveKey:
              summary: Key switched off
              value:
                error: unauthorized
                message: API key is inactive.
    RateLimited:
      description: >
        `rate_limited`: too many requests. Wait the number of seconds in
        `Retry-After`, then retry. See [Errors and rate
        limits](/guides/errors-and-rate-limits#rate-limits).
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            perAccount:
              summary: Per-account limit
              value:
                error: rate_limited
                message: >-
                  Too many requests for this account. Retry after the number of
                  seconds in Retry-After.
            perAddress:
              summary: Per-address limit
              value:
                error: rate_limited
                message: Too Many Requests
    ServerError:
      description: >
        `internal_error`: something went wrong on Hoppier's side. The message
        never contains internal details. Retry with backoff; if it keeps
        happening, email support@hoppier.com.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_error
            message: An unexpected error occurred.
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying.
      schema:
        type: string
      example: '30'
    RateLimitRemaining:
      description: >-
        Per-address limit only. Requests left in the current 10-second window,
        so `0` on a 429.
      schema:
        type: string
      example: '0'
    RateLimitReset:
      description: >-
        Per-address limit only. When the window refills, as a Unix timestamp in
        seconds.
      schema:
        type: string
      example: '1793491210'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_live.<prefix>.<secret>
      description: >
        Send your key in the `Authorization` header: `Authorization: Bearer
        hk_live.…`. The word `Bearer` is case-sensitive.


        Keys are shown once. Treat them like passwords and never put one in code
        that runs in a browser or an app.

````

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