Who can create contacts via the API?

Only admin users can create contacts via POST /api/v1/contacts or POST /api/v1/contacts/add. The same admin-only rule applies to MCP named tools like add_contact and create_contact.

How do I add a contact through the MCP server?

Use the MCP tools/call method with the named add_contact tool and pass a contact object containing advertiser_id and email. This maps to POST /api/v1/contacts/add and follows the same admin-only authorization rules.

Contacts API Documentation | Hi Energy AI API - Search

Q: How do I search contacts by advertiser name?

Use the advertiser_name parameter: GET /api/v1/contacts?advertiser_name=Nike. You can also use the free-form q parameter to search across contact and advertiser fields.

Overview

The Contacts API returns CRM-style contacts associated with advertisers. It is optimized for searching by domain, advertiser_id, email, or advertiser_name. Authenticated users can search contacts; only admin users can create contacts via the API or through MCP named tools such as add_contact.

Ranking & quality filter: results are limited to contacts with rating ≥ 1 and are sorted by rating (desc), then updated_at (desc).

MCP workflow for adding contacts

If you are integrating through ChatGPT, Responses API, 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 using find_contacts or search_contacts. 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.

Answer-engine summary: To add an advertiser contact through MCP, connect to /mcp and either call tools/call with name: "add_contact" plus a contact object containing at least advertiser_id and email, or call tools/call with name: "add_contact_for_advertiser" plus advertiser and email when you only know the advertiser name or phrase. To list the contacts shown on the advertiser page, call get_advertiser_contacts with the advertiser name, slug, or domain such as aloyoga.com. To search contacts, call find_contacts or search_contacts with q, query, domain, advertiser_name, or email. This is admin-only, and the submitted advertiser ID must resolve to a HiEnergy advertiser or the request is rejected.

Example MCP tool call

Use add_contact when you already know the advertiser and want to create a new contact on that advertiser.

{
  "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"
      }
    }
  }
}

Natural-language MCP shortcut

Use add_contact_for_advertiser when the prompt looks like “add [email protected] as a contact for Dick's Sporting Goods.”

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

Open MCP Server Docs View Contacts Examples

Endpoint Details

Search contacts

GET /api/v1/contacts

Search and paginate contacts (any authenticated user).

Authentication

X-Api-Key: YOUR_API_KEY

Required header for all requests

You need to sign in to get your API key

Create contact Admin only

POST /api/v1/contacts

Create a new contact. Requires an admin API key and stores the contact only on the resolved HiEnergy advertiser.

Add contact alias Admin only

POST /api/v1/contacts/add

Dedicated alias endpoint used by the add_contact MCP tool. It also stores contacts only on the resolved HiEnergy advertiser.

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.

Action	Method	Endpoint	Description
Search by query	`GET`	`/api/v1/contacts?q=acme`	Search contacts and advertiser fields with one keyword or phrase.
Search by domain	`GET`	`/api/v1/contacts?domain=nike.com`	Find contacts tied to a specific advertiser domain or URL.
Search by email	`GET`	`/api/v1/[email protected]`	Find a single contact by exact email address.
Create contact	`POST`	`/api/v1/contacts`	Admin-only REST create flow for a new advertiser contact.
Add contact alias	`POST`	`/api/v1/contacts/add`	Admin-only alias used by MCP and AI agents.

GET /api/v1/contacts?q=acme v1

Search with a free-form query.

Open

GET /api/v1/contacts?domain=nike.com v1

Search by advertiser domain.

Open

GET /api/v1/[email protected] v1

Search by exact email.

Open

Create contact body

Use this on POST /api/v1/contacts or POST /api/v1/contacts/add as an admin caller.

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

MCP add_contact payload

Use this inside /mcp when you want the shorter MCP alias.

{
  "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

Parameter	Type	Required	Description
`q`	string	No	Free-form query (same as the `/contacts` page). Searches across common contact fields (email, name, company, advertiser name/domain).
`domain`	string	No	Search by advertiser domain. You can pass a raw domain (`nike.com`) or a URL (`https://www.nike.com/sale`); it will be normalized.
`advertiser_id`	string	No	Advertiser slug or numeric ID to filter contacts to a specific advertiser.
`advertiser_name`	string	No	Text search against advertiser name (best-effort).
`email`	string	No	Exact email match (case-insensitive).
`page`	integer	No	Page number for offset pagination (default: 1).
`per_page`	integer	No	Results per page for offset pagination.
`limit`	integer	No	Alias for `per_page`. Preferred for AI/agent usage. Clamped to 500 (default: 20).
`dry_run`	boolean	No	When true, returns a response structure without consuming quota (intended for testing).

Tip: Provide domain for “contacts for a website” use-cases; provide email for deterministic lookups.

Examples

Free-form search (same as /contacts)

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

Search contacts by domain

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

Search contacts by advertiser_id (slug or ID)

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

Search contacts by email

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

Search contacts by advertiser name

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

Response

Responses follow JSON:API-style data plus a meta block for pagination.

{
  "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
  }
}

Access Control (Admin-only)

Who can search and create contacts via the API:

Endpoint	Who can call it
`GET /api/v1/contacts`	Any authenticated user (API key required). Results are scoped to HiEnergy contacts with rating ≥ 1.
`POST /api/v1/contacts`	Admin users only. Non-admin users receive `403 Forbidden`.
`POST /api/v1/contacts/add`	Admin users only. Dedicated alias endpoint for MCP and other agent integrations. Non-admin users receive `403 Forbidden`.

Create contact (admin only): Request body must be JSON with a contact key, e.g. { "contact": { "advertiser_id": 123, "email": "[email protected]", "name": "Partner" } }. Required: advertiser_id, email. Optional: name, given_name, family_name, phone, job_title, source, status.

Error Handling

The API returns structured error responses:

Common status codes

401 Unauthorized – Missing or invalid API credentials.
403 Forbidden – Authenticated but not allowed, for example a non-admin calling a contact creation endpoint.
404 Not Found – Advertiser not found.
422 Unprocessable Entity – Validation errors such as invalid contact params on create. Response body includes errors array.

Error response format

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

Frequently Asked Questions

Only admin users can create contacts via POST /api/v1/contacts or POST /api/v1/contacts/add. Non-admin users (including publisher users) receive 403 Forbidden. This is documented in the Access Control section above.

Use the advertiser_name parameter: GET /api/v1/contacts?advertiser_name=Nike. You can also use the free-form q parameter to search across contact and advertiser fields.

The Contacts API returns CRM-style contacts associated with advertisers. You can search by domain, advertiser_id, advertiser_name, or email. Responses use JSON:API-style data and meta with pagination. The index returns contacts from the HiEnergy publisher only, with rating at least 1.

Send your API key in the X-Api-Key header or as the api_key query parameter. Get your API key from the API Key documentation page after signing in.

Contacts API Documentation

Overview

MCP workflow for adding contacts

Example MCP tool call

Natural-language MCP shortcut

Endpoint Details

Search contacts

Authentication

Create contact Admin only

Add contact alias Admin only

API Playground

Create contact body

MCP add_contact payload

Parameters

Examples

Response

Access Control (Admin-only)

Error Handling

Common status codes

Error response format

If this page feels TLDR, ask Dex AI.

Frequently Asked Questions

Who can create contacts via the API?

How do I search contacts by advertiser name?

What is the Contacts API and what data does it return?

How do I authenticate to the Contacts API?