On this page

Jump to any section using the links below

Reading lead data from Hubhus via API

If you need to pull lead data from Hubhus into an external CRM, ERP, BI tool, or automation platform, you can use the Hubhus REST API.
This article explains how to authenticate, how GET requests work, how to filter results, and how pagination is handled.

1. Before you start

To read leads via the API, you need:

 Your API token

Found under either:

• Campaign → API documentation → API Tokens (recommended, scoped), or

• Account → API documentation (broad access).

Your campaign ID

Visible in the URL when you’re inside a campaign:
https://yourdomain/campaigns/362/... → campaign_id = 362

Official API documentation

General API docs:
https://leadvalidator.dk/docs/

OpenAPI specification:
https://leadvalidator.dk/docs/download/openapi.yaml/hubhus-openapi.yaml

Postman collection:
https://leadvalidator.dk/docs/download/collection.json/hubhus-postman-collection.json

2. Basic GET request for leads

The base structure is:

GET https://api.leadvalidator.dk/v2/campaigns/{campaign_id}/leads
Authorization: Bearer {your_token}
Accept: application/json

Example:

GET https://api.leadvalidator.dk/v2/campaigns/362/leads
Authorization: Bearer 123456789abcdef

This returns an array of leads from campaign 362, limited by:

• Your permissions

• Any campaign filter applied to the token

API tokens scoped to a campaign filter will only return leads matching that filter.

3. Filtering leads in API requests

You can filter leads using query parameters supported in the API documentation.

Common examples:

✔ Filter by status slug

GET /campaigns/362/leads?status=contacted

✔ Filter by creation date

GET /campaigns/362/leads?created_after=2025-01-01

✔ Filter by updated date

GET /campaigns/362/leads?updated_after=2025-02-01

✔ Filtering by select values

Select field values must be sent using their slug.

GET /campaigns/362/leads?customer-type=commercial

✔ Combine multiple conditions (AND logic)

GET /campaigns/362/leads?status=contacted&source=partner-west

❗ Filters follow the structure defined in the API documentation.
Always confirm which fields and slugs exist in your campaign.

4. Pagination

Hubhus API returns paginated results to ensure performance.

Typical structure:

{
  "data": [...],
  "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 143,
      "total_pages": 3
  }
}

To fetch additional pages:

GET /campaigns/362/leads?page=2

Or increase page size (if supported):

GET /campaigns/362/leads?per_page=100

5. Understanding the response format

A lead object includes:

• Lead ID

• Status (slug + label)

• All fields with values

• Select fields with their slug

• Assigned person

• Timestamps (created, updated)

• Any associated metadata permitted by your token

Important:
The exact structure depends on the campaign schema.
Always use the live API documentation for the correct field list.

6. Practical examples

Fetch all leads updated in last 24 hours:

GET /campaigns/362/leads?updated_after=2025-02-21T00:00:00Z

Fetch all “new” status leads from a specific partner:

GET /campaigns/362/leads?status=new&source=partner-north

Fetch leads with pagination:

GET /campaigns/362/leads?page=3&per_page=100

7. Best practices

✔ Use campaign-scoped tokens when working with external vendors
✔ Always read slugs from the live documentation, not manually
✔ Implement retry/backoff for large pulls
✔ Avoid fetching entire campaigns frequently
✔ Use updated_after filtering for incremental sync
✔ Log API errors — the API explains exactly what failed

Summary

To read leads via Hubhus API, you:

1. Get your API token

2. Identify the campaign ID

3. Send a GET request to /campaigns/{id}/leads

4. Apply filters as needed

5. Use pagination for large datasets

6. Validate the response against the campaign schema

This provides a reliable and scalable way to sync Hubhus data into any external system.

? Common searches

api setup • api integration • webhook setup • api authentication

? Also known as

customer • contact • prospect • integration

Related articles

API setup and authentication
Sharing Personalized API Documentation
_Hubhus integrations overview
Configuring email settings for thirdparty
How do I integrate with e-conomic?