An address is a business address of a given type. A business can carry several: a registered address for the legal entity, a mailing address for correspondence, a physical address, and more. Each address 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.
Add a separate mailing address for correspondence.
Update an address when the business moves.

🚧
PENDING-PUBLISH
The boarding API Reference is pending publication; the ref: targets on this page are placeholders. Replace each with the real boarding-spec operationId once the boarding reference ships.

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, mailing, physical, headquarters, home, work).

Scenario 1: Add an address

Add a business 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_54",
  "uri": "/v1/businesses/{businessId}/addresses/addr_54",
  "type": "mailing",
  "line1": "100 Congress Ave",
  "city": "Austin",
  "stateProvince": "TX",
  "postalCode": "78701",
  "countryCode": "US",
  "isPrimary": true
}

Addresses supplied inline on a business create come back with generated addr_… ids too.

Scenario 2: Update an address when the business moves

Send only the fields that change; the update is a partial merge. Make a PATCH request to /v1/businesses/{businessId}/addresses/{addressId}.

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

Manage addresses

List or read one: GET /v1/businesses/{businessId}/addresses, or GET /v1/businesses/{businessId}/addresses/{addressId} for one.
Update: PATCH /v1/businesses/{businessId}/addresses/{addressId}; all fields are optional (partial update).
Remove: DELETE /v1/businesses/{businessId}/addresses/{addressId} removes the address.

Request reference

Field	Required	Description
`type`	✓	One of `registered`, `mailing`, `physical`, `headquarters`, `home`, `work`.
`line1`	✓	Street address.
`line2`	Optional	Additional street detail.
`city`	✓	City.
`stateProvince`	✓	State or province.
`postalCode`	✓	Postal code.
`countryCode`	✓	Country code.
`isPrimary`	Optional	Whether this is the primary address.

Statuses

An address does not run its own lifecycle; it is validated as part of the business's requirements. A missing registered address surfaces on the service's missingFields. See Status lifecycle and Underwriting exceptions.

Sandbox testing

Use the sandbox to add and update addresses before going live.

Scenario	Test data	Expected result
Add an address	A valid `type` and complete address fields	`201 Created` with an `addr_` id
Partial update	`PATCH` with only `line1`	`200 OK`; other fields unchanged
Missing required field	Omit `postalCode`	Submit-time validation error

Go live

The shared pre-production checklist is in Getting Started. Specific to addresses:

The business has a registered address for the legal entity.
Any mailing or physical address a location needs is present.

Best practices

Practice	Description
Set the right `type`	Keep the registered, mailing, and physical addresses distinct so each is used where it should be.
Update in place	When the business moves, `PATCH` the existing address rather than adding a duplicate.
Store the `addr_` id	You need it to update or remove a specific address.

Next steps

Locations

Add the sites where a business operates, each with its own address.

Manage a business

Update the business's own details.

PENDING-PUBLISH

Scenarios

Scenario 1: Add an address

Scenario 2: Update an address when the business moves

Manage addresses

Request reference

Statuses

Sandbox testing

Go live

Best practices

Next steps

See also