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

Available tools: list_leads and get_lead with read permission; create_lead and update_lead with write permission. 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.