Contacts API Documentation

Overview

The Contacts API returns CRM-style contacts associated with advertisers. It is optimized for searching by domain, advertiser_id, email, advertiser_name, and source filters. MCP clients can also use aliases such as search, keyword, and website, which the MCP layer normalizes to REST parameter names. Authenticated users can search contacts. Direct REST create requires an admin or paid publisher API key. Any authenticated MCP user can add contacts through tools such as add_contact; MCP-created contacts are stamped with source HiEnergy MCP (caller email).

MCP workflow for adding contacts

If you are integrating through Claude or another MCP-compatible client, you can add contacts through the MCP server using the named add_contact tool or the natural-language-friendly add_contact_for_advertiser tool, list the same advertiser-page contacts with get_advertiser_contacts, and search them with search_contacts (preferred in tools/list; find_contacts remains a hidden legacy alias). The add tool maps directly to POST /api/v1/contacts/add, and the advertiser contacts tool maps directly to GET /api/v1/advertisers/:id/contacts.

{
  "method": "tools/call",
  "params": {
    "name": "add_contact",
    "arguments": {
      "contact": {
        "advertiser_id": 123,
        "email": "[email protected]",
        "given_name": "Jane",
        "family_name": "Doe",
        "job_title": "VP Partnerships"
      }
    }
  }
}

{
  "method": "tools/call",
  "params": {
    "name": "add_contact_for_advertiser",
    "arguments": {
      "advertiser": "Dick's Sporting Goods",
      "email": "[email protected]",
      "given_name": "Joe",
      "family_name": "Blow"
    }
  }
}

Endpoint Details

API Playground

Click Test to run a live GET request, or use the copy-paste snippets below for the create and MCP add flows. Sign in to enable live testing with your API key.

{
  "contact": {
    "advertiser_id": 123,
    "email": "[email protected]",
    "given_name": "Jane",
    "family_name": "Doe",
    "job_title": "VP Partnerships",
    "phone": "+1-555-0100",
    "source": "playground"
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "add_contact",
    "arguments": {
      "contact": {
        "advertiser_id": 123,
        "email": "[email protected]",
        "given_name": "Jane",
        "family_name": "Doe"
      }
    }
  }
}

Parameters

Examples

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/contacts?q=alo+yoga&limit=10"

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/contacts?domain=example.com&limit=10"

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/contacts?advertiser_id=example&limit=10"

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/[email protected]"

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/contacts?advertiser_name=Example&limit=10"

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://app.hienergy.ai/api/v1/contacts?domain=example.com&advertiser_name=Example&sources=StoreLeads,HiEnergy%20Hubspot&has_linkedin=true&limit=10"

Response

Responses follow JSON:API-style data plus a meta block for pagination. email is returned for admin and paid callers (and MCP-proxied responses); other authenticated callers receive null. meta also includes searchkick_available.

{
  "data": [
    {
      "id": "123",
      "type": "contact",
      "attributes": {
        "id": 123,
        "email": "[email protected]",
        "name": "Partnerships",
        "company_name": "Nike",
        "job_title": "Affiliate Manager",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-10T00:00:00Z",
        "advertiser": {
          "id": 42,
          "name": "Nike",
          "slug": "nike",
          "domain": "nike.com",
          "url": "https://www.nike.com"
        }
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_count": 1,
    "total_pages": 1,
    "searchkick_available": true
  }
}

Access Control

Who can search and create contacts via the API:

Error Handling

The API returns structured error responses:

{
  "errors": ["Email can't be blank", "..."],
  "error": { "code": "UNAUTHORIZED", "message": "..." }
}