Custom Address Metadata

About custom metadata

Custom metadata can be provided when creating an address via the API. You can provide it by passing metadata when calling Create a location. Stable will include this metadata on APIs and Webhooks relating to the address and each mail item received at the address so that you can tie addresses to entities in your own system.

Pass an object when you create the address:

curl -X POST https://api.usestable.com/v1/locations \
  -H "x-api-key: $STABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locationCode": "ATL3",
    "metadata": { "customerId": "cus_789" }
  }'

The object will be returned on the address object in these places:

• On the address object, under metadata.
• On Mail Items, in location.metadata. This is populated for API responses and for webhooks.

Limitations

• Only top-level keys are allowed (nesting is not allowed).
• Each value must be a string or a number.
• You must set metadata when creating the address.
• You cannot search addresses by metadata fields.
• If you are using the API to offer addresses to your end users, please see Stable for Platforms.

Example use case

1. Store the ID of your customer in metadata when you create the address.
2. Receive a mail item and catch its webhook events (mailItem.created).
3. Read the customer ID from location.metadata in the event.
4. Use the ID to locate the record of your customer without storing the Stable location ID.