An address is a business address of a given type. One business can carry several: a registered address for the legal entity, a mailing address for correspondence, a physical address, and more. Each is its own record with its own id. For the full field list, jump to the Request reference.

Common use cases

• Add the registered address of the legal entity. See Scenario 1.
• Add a separate mailing address for correspondence. See Scenario 1.
• Update an address when the business moves. See Scenario 2.

Scenarios

Each address is a separate record keyed by its type. Add as many as the business needs, and update any one of them in place.

Before you begin (all scenarios)

• You have the businessId the address belongs to.
• You know the address type: registered, physical, mailing, headquarters, home, or work.

Scenario 1: Add an address

Make a POST request to /v1/businesses/{businessId}/addresses.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/addresses \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mailing",
    "line1": "100 Congress Ave",
    "city": "Austin",
    "stateProvince": "TX",
    "postalCode": "78701",
    "countryCode": "US",
    "isPrimary": true
  }'

Response: 201 Created.

{
  "id": "addr_4a2f7c",
  "uri": "/v1/businesses/{businessId}/addresses/addr_4a2f7c",
  "type": "mailing",
  "line1": "100 Congress Ave",
  "city": "Austin",
  "stateProvince": "TX",
  "postalCode": "78701",
  "countryCode": "US",
  "isPrimary": true
}

Store the id. Addresses supplied inline on a business create come back with generated addr_ ids too.

Scenario 2: Update an address

Make a PATCH request to /v1/businesses/{businessId}/addresses/{addressId}. The update is a partial merge, so send only the fields that change.

curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/addresses/addr_4a2f7c \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "901 Commerce St",
    "postalCode": "78702"
  }'

Manage addresses

An address has no lifecycle of its own; it is validated as part of the business. A missing registered address shows on the service's missingFields. See Status lifecycle.

Request reference

Next steps

See also

• Create a business: add addresses inline in the composite create
• Businesses: how addresses fit the entity model
• Status lifecycle: how the business moves through underwriting