Locations

{
  id: string;
  status: 'active' | 'inactive' | 'pending';
  address: {
    line1: string;
    line2: string;
    city: string;
    state: string;
    postalCode: string;
  };
  type: 'cmra' | 'registeredAgent';
  onboarding: {
    status: 'authorize' | 'sign' | 'verify' | 'complete';
  };
  metadata: object;
}

Attributes

id string Unique identifier for the object.

status string

The top-level status of the location. One of:

• active: The location is fully provisioned and ready to use.
• inactive: The location has been deactivated and is no longer receiving mail.
• pending: The location has been requested but is still being provisioned. This applies to registered agent locations only. CMRA locations are returned as active immediately on creation. A pending registered agent location will transition to active once provisioning completes. You can poll GET /v1/locations/{id} to detect the transition. For more on this flow, see Create a Registered Agent Location.

📘

status vs onboarding.status

The top-level status describes whether the location exists and is provisioned in our system. The nested onboarding.status describes where a CMRA location is in the USPS Form 1583 onboarding flow. They are independent values. A CMRA can be status: "active" while still having onboarding.status: "authorize".

address.line1 string The first line of the address for this location.

address.line2 string The second line of the address for this location.

address.city string The city where this location resides.

address.state string The state where this location resides.

address.postalCode string The USPS 5-digit postal code associated with this location.

type string

Whether the location is a cmra (commercial mail receiving agency) or a registeredAgent. See Location codes for the full list of supported codes for each type.

onboarding.status string

The current state of USPS Form 1583 onboarding for this location:

• authorize
• sign
• verify
• complete

This field is primarily meaningful for CMRA locations, which require USPS Form 1583 onboarding. Registered agent locations do not go through this flow.

metadata nullable object

A customizable key-value object to associate with your location. The object can only be one level deep, where each key is a string and each value is either a number or string.