Locations and scoping

A location represents a specific business entity, such as a store, office, or client account. All CRM data in HowdyBell is scoped to a location. You must provide a valid location_id in most API requests.

Why Locations Matter

1. Data Isolation: Contacts, conversations, and tasks belong to a specific location.
2. Multi-tenant Support: A single workspace can manage multiple locations.
3. Security: API keys are scoped to a workspace, but data access is further restricted by location.

Retrieving Locations

Use the List locations endpoint to list all locations in your workspace.

curl -X GET "https://howdybell.com/api/v1/locations" \
  -H "Authorization: Bearer hb_live_your_key_here"

Response Example

{
  "data": [
    {
      "id": 101,
      "name": "Downtown Store",
      "address1": "100 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "phone_public": "512-555-0100",
      "timezone": "America/Chicago",
      "website": "https://example.com"
    },
    {
      "id": 102,
      "name": "Uptown Store",
      "address1": "200 Oak Ave",
      "city": "Austin",
      "state": "TX",
      "zip": "78702",
      "phone_public": "512-555-0200",
      "timezone": "America/Chicago",
      "website": "https://example.com"
    }
  ]
}

Using Location IDs

Include the location_id in query parameters for GET requests and in the request body for POST, PATCH, and DELETE requests.

GET Request Example

curl -X GET "https://howdybell.com/api/v1/contacts?location_id=101" \
  -H "Authorization: Bearer hb_live_your_key_here"

POST Request Example

curl -X POST "https://howdybell.com/api/v1/contacts" \
  -H "Authorization: Bearer hb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": 101,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]"
  }'

Validation Rules

1. The location_id must be a positive integer.
2. The location must belong to the workspace associated with your API key.
3. If the location_id is missing or invalid, the API returns a 404 error with {"error": "location.not_found"}.
4. You cannot access data from a location in a different workspace, even if you know the ID.

OAuth Location Locking

Marketplace apps using OAuth tokens are locked to a specific location. This means:

1. The token is issued for a single location_id.
2. Requests to other locations return 404 errors.
3. The List locations endpoint returns only the locked location.

Note: If you are building a marketplace app, ensure you request the correct location ID during the OAuth flow.

Common Errors

Status Code	Error Body	Cause
404	{"error": "location.not_found"}	Invalid ID, wrong workspace, or OAuth lock mismatch.
401	{"error": "invalid_api_key"}	Authentication failed before location check.

Best Practices

1. Cache location IDs to avoid repeated calls to location.index.
2. Validate location_id values before making API calls.
3. Handle 404 errors gracefully in your application.
4. Log location IDs in error reports for easier debugging.