API & MCP

API & MCP Reference.

Everything you need to call the EQALL API and MCP server: authentication, paging, errors, and links to each resource. New here? Start with the developer guide.

Generated from the EQALL API on October 23, 2026 · API version 1.0 · OpenAPI JSON

Introduction

The EQALL API gives your apps and AI agents read access to contacts, companies and meetings, and lets them add contacts. Every call acts as the user who created the API key and sees only what that user can see in EQALL.

Base URL: https://api.eqall.com. Requests and responses are JSON. Dates are ISO 8601 in UTC. IDs (contactId, companyId, meetingId) are UUIDs.

For setup, connecting AI agents and the Postman collection, see the developer guide.

Authentication

Create a key in EQALL under Settings → Integrations → API & AI agents and send it as a bearer token:

Header

Authorization: Bearer eqk_your_key_here

Keys are read-only unless created with Allow adding contacts (write:contacts). Revoking a key stops it immediately.

OAuth (Claude, ChatGPT and other MCP clients)

AI tools that add EQALL as a connector sign the user in with OAuth 2.1 instead of using a key, following the MCP authorization spec. Calls without a valid token return 401 with a WWW-Authenticate header that points to the discovery documents:

Protected resource	`https://api.eqall.com/.well-known/oauth-protected-resource`
Authorization server	`https://api.eqall.com/.well-known/oauth-authorization-server`
Resource	`https://api.eqall.com/mcp`
Scopes	`read`, `write:contacts`, plus `offline_access` for a refresh token
Flow	Dynamic Client Registration, then authorization code with PKCE (S256). Public clients only. Callback URLs must use https, or http on localhost.
Tokens	Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use.

OAuth access tokens work on /mcp and /external/*, the same as keys. Users can disconnect a tool at any time under Settings → Integrations → API & AI agents.

Check a key

GET/external/whoami

Shows the user, company and permissions the API key acts as.

Response

userobject

contactIdstring

The key user's public ID (same as their contactId)

firstNamestring

lastNamestring

emailstring

companyobject, nullable

companyIdstring

Public company ID

namestring

apiKeyobject

typeenum

An EQALL API key, or an OAuth token issued to an AI tool

apikeyoauth

prefixstring, nullable

First characters of the key (API keys only)

scopesarray of string

Errors

401 · Missing, unknown or revoked API key 429 · Rate limit exceeded (per key)

Request

curl "https://api.eqall.com/external/whoami" \
  -H "Authorization: Bearer $EQALL_KEY"

Response · 200

{
  "user": {
    "contactId": "0a7e5d3b-9c21-4f68-b4e2-7d1a6c9f3e05",
    "firstName": "Sam",
    "lastName": "Rivera",
    "email": "sam@yourco.com"
  },
  "company": {
    "companyId": "5e2c8f1a-3d7b-4a96-8e0c-1b4f7a2d9c63",
    "name": "YourCo"
  },
  "apiKey": {
    "prefix": "eqk_9fX2kLq7",
    "scopes": [
      "read",
      "write:contacts"
    ]
  }
}

Pagination

Search endpoints return one page plus a cursor:

Response shape

{
  "contacts": [
    "…"
  ],
  "nextCursor": "eyJvIjoyMH0"
}

Pass nextCursor back as cursor (with the same filters) for the next page. null means the last page. limit sets the page size: default 20, max 50.

Errors

Errors use standard HTTP status codes with a JSON body such as { "statusCode": 404, "message": "Meeting not found", "error": "Not Found" }.

Status	Meaning
`400`	Malformed ID or cursor
`401`	Missing, unknown or revoked API key
`403`	The key lacks a permission, e.g. `write:contacts`
`404`	Not found, or not visible to the key's user (the two are deliberately indistinguishable)
`422`	Invalid parameters. The message lists each problem.
`429`	Rate limit exceeded. Wait and retry.

Rate limits

60 requests per minute per API key or connected AI tool. Over the limit, requests return 429 until the minute resets.

Resources

Each resource has its own page with every endpoint's parameters, response fields and examples.

Contacts

GETFind contacts

POSTAdd a contact

GETGet contact details

Companies

GETFind companies

GETGet company details

Meetings

GETFind meetings

GETGet meeting details

MCP server

POST/mcp

Model Context Protocol over Streamable HTTP, stateless. Send JSON-RPC 2.0 messages; no initialize call is required. Requires the header Accept: application/json, text/event-stream. Responses arrive as a server-sent event (data: line). Tools: findContact, getContactDetails, createContact, findCompany, getCompanyDetails, findMeetings, getMeetingDetails — call tools/list for their input schemas.

Each tool takes the same inputs as its REST endpoint (path and query parameters become tool arguments) and returns the same JSON, as text in result.content[0].text. On failure, result.isError is true and the text explains why.

Tools

Tool	Same as
`findContact`	GET/external/contacts
`createContact`	POST/external/contacts
`getContactDetails`	GET/external/contacts/{contactId}
`findCompany`	GET/external/companies
`getCompanyDetails`	GET/external/companies/{companyId}
`findMeetings`	GET/external/meetings
`getMeetingDetails`	GET/external/meetings/{meetingId}

Headers

Authorizationrequired

Bearer eqk_…, or an OAuth access token (see Authentication)

Acceptrequired

application/json, text/event-stream

Request · tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "findContact",
    "arguments": {
      "query": "jane acme"
    }
  }
}

Response · server-sent event

data: {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"contacts\":[…],\"nextCursor\":null}"
      }
    ]
  }
}