API reference
The HowdyBell REST API speaks JSON over HTTPS. Every request is made against https://howdybell.com/api/v1 and authenticated with a bearer token.
Authentication
Send Authorization: Bearer YOUR_TOKEN on every request. The token is either a workspace API key (it starts with hb_live_, see Authentication) or an OAuth access token your marketplace app received. A missing, wrong or revoked token gets 401 with {"error": "invalid_api_key"}.
Locations
Most endpoints work inside one location (one store or office). Pass location_id in the query string on GET requests and in the JSON body on POST, PATCH and DELETE requests. A location outside your workspace, or any record outside that location, answers 404 with an error such as {"error": "contact.not_found"}.
Rate limits and versions
Each token can make 120 requests per minute. Above that you get 429 Too Many Requests; wait and retry. Every response carries an X-HowdyBell-Version header (today 2026-09-22).
Errors
Invalid input answers 422 with a message and an errors object that lists the problem for each field.
Contacts
- GETList contacts
/api/v1/contacts - POSTCreate a contact
/api/v1/contacts - POSTUpsert a contact
/api/v1/contacts/upsert - GETGet a contact
/api/v1/contacts/{id} - PATCHUpdate a contact
/api/v1/contacts/{id} - DELETEDelete a contact
/api/v1/contacts/{id} - POSTAdd a tag to a contact
/api/v1/contacts/{id}/tags - DELETERemove a tag from a contact
/api/v1/contacts/{id}/tags/{tagId} - POSTAdd a note to a contact
/api/v1/contacts/{id}/notes