Lead management API and MCP for AI agents

REST API quick start

In your workspace, open Developer settings → API & MCP access. Create a read-only token first. Replace YOUR_WORKSPACE and YOUR_TOKEN below. Keep the token in your backend’s secret manager.

The guided setup includes a read-only connection check and examples for your workspace. GET /api/v1/connection confirms authentication and returns connected and scopes without accessing lead records. A successful built-in check verifies your token; run a request from your own app or agent to confirm that external connection.

curl 'https://YOUR_WORKSPACE.app.happitap.com/api/v1/leads?limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Write requests also need Content-Type: application/json. Lists return data, page and has_more; single records return data. Returned fields are id, name, email, phone, notes, is_contacted, follow_up_date and created_at. Responses: 201 created, 401 invalid/expired token, 403 insufficient access, 404 missing lead/workspace, 409 incomplete workspace, 422 validation error, 429 rate limit. Rate limit: 60 requests per minute per source IP across these endpoints.

curl -X POST 'https://YOUR_WORKSPACE.app.happitap.com/api/v1/leads' \
  -H 'Authorization: Bearer YOUR_WRITE_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example contact","email":"contact@example.com","notes":"Requested a demo"}'

Creating a lead does not send an email, WhatsApp message or follow-up reminder. Creation is not idempotent: avoid blindly retrying an uncertain POST response, and check existing records before resubmitting.

Connect an MCP client

Choose a remote Streamable HTTP connection. Use https://YOUR_WORKSPACE.app.happitap.com/mcp and set Authorization: Bearer YOUR_TOKEN as a custom header. Configuration labels vary by client. This is manual token authentication, not OAuth; clients that only support OAuth connections cannot connect yet.

The server supports protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. Initialize first, then send the negotiated MCP-Protocol-Version header. Include Accept: application/json, text/event-stream and Content-Type: application/json. Responses use JSON; there is no persistent session or server-initiated SSE stream.

curl 'https://YOUR_WORKSPACE.app.happitap.com/mcp' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

Tools include lead lookup and updates, company records and contact links, custom-field discovery and values, saved views and field proposals. Tool discovery only exposes tools permitted by your token. Ask your agent to confirm record changes with you. Treat lead notes and contact fields as data, not instructions.

Use one token per integration. Tokens expire after 7, 30, 90 or 365 days in the UI and can be revoked immediately. Only verified workspace administrators can manage tokens. Tokens are restricted to the issuing workspace and stored as hashes. Connect from a backend or supported desktop agent, not a public browser script.

Understand connection activity

Refresh Connection activity in your workspace to see your tokens’ latest 50 requests, with protocol, operation, HTTP status, outcome and elapsed time. The retained history is limited to 1,000 requests across the workspace within 30 days. Older entries are removed when requests arrive or the activity page opens. Summary counts cover your retained history, not lifetime usage.

Failed MCP tool calls count as failures even when HTTP returns 200. Troubleshooting hints help distinguish permissions, input errors and protocol issues. Recognized-token responses include X-Request-Id for matching a request to its activity entry.

Activity does not store credentials, lead fields, search terms, request bodies, response bodies or raw error text. Unknown or revoked tokens, rejected origins and requests stopped by the rate limiter cannot be attributed to a token and are not listed. Each administrator sees only their own tokens’ activity.

Companies and custom fields

Company records use /api/v1/accounts with accounts:read or accounts:write. Linking a person to a company also requires leads:write. Read linked contact details with leads:read.

Custom-field actions use POST /api/v1/custom-fields/{action}. Start with list_custom_fields and an entity of contact or account. Use get_custom_values, set_custom_values and query_custom_fields for values and filters. Combine fields:read/write with the corresponding leads:read/write or accounts:read/write permissions.

POST /api/v1/custom-fields/list_custom_fields
{"entity":"contact"}

POST /api/v1/custom-fields/set_custom_values
{"entity":"contact","id":123,"values":{"cf_budget":"2500.00"}}

Discover the field first: cf_budget is an example and must exist in that workspace. Values must match the field type. list_saved_views and run_saved_view reuse saved criteria. propose_custom_field submits a missing field for administrator review; agents cannot approve their own proposals. The same action names are available through MCP when the token has permission.

Mapped incoming deliveries

For a connector, use Integrations → Field mapping and delivery history to choose contact or company fields, conversion rules and an update mode. Create a source-specific ingestion key there. This key is separate from an API/MCP token.

Send JSON to POST /api/integrations/{source}/ingest on your workspace host with Authorization: Bearer YOUR_INGESTION_KEY. Include a unique Idempotency-Key header. Reuse it for identical retries; use a new key for corrected source data. Successful deliveries are deduplicated for seven days. HTTP 422 identifies invalid fields; fix the mapping and retry from delivery history, or correct the source and resend. For 429 or 5xx, retry with backoff.

Source examples include google_ads, google_forms, zapier, make and apify. Native provider webhooks may have their own signatures and payload formats. Failed payloads are encrypted and retained for up to seven days for administrator retry; successful payload bodies are removed. Contact/company matching and overwrite choices are controlled by the saved mapping.