Make your first API call

The HowdyBell REST API uses a base URL of https://howdybell.com/api. All requests require an API key for authentication. This guide walks you through creating a key and making your first request.

Create an API key

1. Sign in to HowdyBell as an owner or manager.
2. Open Settings, then Integrations.
3. In the API keys and webhooks card, type a Key name (for example "Website sync") and click Create key.
4. Copy the key. It starts with hb_live_.

Important: The full API key is shown only once. Store it securely. You cannot retrieve it again later.

Step 1: List Locations

The first step is to verify your key works and identify your location_id. Most CRM endpoints require a location_id to scope data to a specific business entity.

Run this command with curl:

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

Step 2: Inspect the Response

A successful response returns a JSON array of locations. Each object contains an id and a name.

{
  "data": [
    {
      "id": 101,
      "name": "Main Office",
      "address1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "phone_public": "512-555-0100",
      "timezone": "America/Chicago",
      "website": "https://example.com"
    }
  ]
}

Save the id value (for example, 101). You will use this as the location_id parameter in subsequent requests.

Step 3: List Contacts

Now that you have a valid location_id, you can retrieve contact data. This endpoint returns a paginated list of contacts.

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

The response includes a data array, a next_cursor for pagination, and a total count.

{
  "data": [
    {
      "id": 5001,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "512-555-0123"
    }
  ],
  "next_cursor": "eyJwYWdlIjoyfQ",
  "total": 150
}

Troubleshooting

If you receive a 401 error with the body {"error": "invalid_api_key"}, check the following:

1. Ensure the Authorization header uses the Bearer scheme.
2. Verify there is a single space between Bearer and the key.
3. Confirm the key has not been revoked.
4. Check for extra whitespace or newlines in the key string.

If you receive a 404 error with {"error": "location.not_found"}, the location_id does not belong to your workspace. Use the List locations endpoint to find valid IDs.