Documentation

AI Dealigence exposes the same objective-driven research engine the product uses internally - organisation discovery, function mapping, person discovery, verification, evidence, and scoring - as an API and an MCP server, so an agent or your own backend can use it directly.

It is not a contact database. Every response is grounded in evidence gathered for that specific objective, not a static record.

One table, kept accurate - every status here was checked against production directly, not read off a spec. If a feature is mentioned anywhere else on this site (pricing, FAQ, homepage) and you want to know whether you can actually rely on it today, this is the page to trust.

1. Sign in at aidealigence.com and create an API key from your account.

2. Submit an objective:

curl https://aidealigence.com/api/v1/objectives \
  -H "Authorization: Bearer dl_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"objective": "Find family offices in New York investing in growth-stage technology"}'

3. Poll until it’s done - this is real research, it takes minutes:

curl https://aidealigence.com/api/v1/objectives/{id} \
  -H "Authorization: Bearer dl_live_xxx"

Base URL: https://aidealigence.com/api. Every endpoint on this page is relative to that - POST /v1/objectives means POST https://aidealigence.com/api/v1/objectives, in full, every time.

Every request carries Authorization: Bearer dl_live_xxx (or dl_test_xxx for a test-environment key). Create, list, and revoke keys via POST /v1/keys, GET /v1/keys, DELETE /v1/keys/{id} - those three endpoints are authenticated with your normal account session, not an API key, since they manage the keys themselves.

A key is shown in full exactly once, at creation. Only its hash is ever stored; it cannot be retrieved again - create a new one if it’s lost.

POST /v1/objectives is the primary endpoint: submit an objective, get back a ranked, evidence-backed shortlist of people once research completes. Real research is asynchronous - the initial response is {"status": "researching"}; poll GET /v1/objectives/{id} until status is completed or failed.

Supports an Idempotency-Key header - retry a timed-out request with the same key and the same body and you’ll get the original response back, not a second research run.

Two depth variants trade cost for thoroughness - the same real pipeline, not a stripped-down fake: POST /v1/objectives/quick (fewer sources, lower cost, faster) and POST /v1/objectives/deep (more sources, more candidates compared, higher cost). Check the cost before you commit to either with POST /v1/objectives/estimate, which runs nothing and returns an estimated credit cost, £ cost, and latency based on recent runs at that depth.

Once running, POST /v1/objectives/{id}/cancel stops the objective for real - it halts the live research task and its ongoing spend, not just a status flag while work continues unseen. POST /v1/objectives/{id}/refresh re-runs a completed or cancelled objective from scratch for current results, billed like a new run.

0 qualified candidates is a genuine, high-fidelity negative signal, not a bug - it means your constraints exceed what’s currently verifiable in public evidence, not that nothing exists. This is never billed: a completed run with nothing to recommend confidently doesn’t consume a credit or your free objective.

The web app surfaces this as a Refine Objective panel - 2-3 concrete rewordings generated from exactly which scoring dimension held back the near-miss candidates that were found (objective relevance, functional responsibility, decision authority, organisation type, geography, or access), plus a breakdown of how many near-misses fell short on each. Click a suggestion to re-run with it pre-filled, no re-typing.

Via the API: GET /v1/objectives/{id} already returns recommendations: [] honestly when nothing qualified - check alternative_people on the human web app’s own GET /research/{id}/report for who came close, and GET /research/{id}/smart-retry for the same refinement suggestions and rejection-category breakdown the UI uses.

Re-submitting a near-identical objective within 24 hours triggers a confirmation prompt rather than silently spending credits again on a very likely repeat outcome - the exact objective text is compared against your recent zero-result runs, not blocked outright, just flagged before you commit.

POST /v1/people/resolve and POST /v1/companies/resolve are objectives scoped to finding a person at a specific company, or the relevant organisations for an objective - both real research, both asynchronous, same polling pattern as objectives.

POST /v1/functions/resolve is different: genuinely fast and synchronous, one reasoning call, no full research run - use it when you just need to know which department owns an objective.

POST /v1/verify checks whether a person already surfaced by one of your objectives still holds their role, returning one of verified, likely, uncertain, or not_found - never a single blurred confidence number standing in for all of that.

GET /v1/evidence/{id} returns the underlying claim, quoted text, source, and confidence behind any recommendation.

POST /v1/access/resolve returns a legitimate way to reach a person: a company contact page, a published email, a LinkedIn profile. Contact details are published with their source. A work email we infer from a company’s published email format is labelled Likely. Data from a licensed provider is labelled as such. We never use leaked or breached data.

POST /v1/batch/objectives groups several real objective runs under one id. Credits for the whole batch are checked up front - a batch that can only be partially afforded fails entirely with INSUFFICIENT_CREDITS rather than running some and silently dropping the rest. GET /v1/batch/{id} returns aggregate progress; GET /v1/batch/{id}/results returns every member’s full result.

Register a URL for objective.completed, objective.failed, or batch.completed via POST /v1/webhooks (account-session authenticated, scoped to one of your API keys). Every delivery is signed - verify it with HMAC-SHA256 over the raw request body using your webhook’s secret, checked against the X-Dealigence-Signature header. The header is a plain lowercase hex digest - no sha256= prefix.

Always verify against the raw request body, before it’s parsed as JSON - re-serialising and re-signing a parsed object won’t match.

Node.js

const crypto = require("crypto");

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody) // Buffer or raw string - the unparsed request body
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "utf8"),
    Buffer.from(signatureHeader, "utf8"),
  );
}

Python

import hashlib
import hmac

def is_valid_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Both examples use a constant-time comparison (crypto.timingSafeEqual / hmac.compare_digest) rather than === or == - a plain equality check leaks timing information an attacker can use to guess the signature byte by byte.

A live MCP server at aidealigence.com/mcp - both with and without a trailing slash complete the handshake correctly, authenticated the same way as the REST API - pass your key as Authorization: Bearer dl_live_xxx in your MCP client’s headers. See the MCP page for the full tool list and client configuration.

Structured error codes, not a bare 500:

INSUFFICIENT_CREDITS   402
IDEMPOTENCY_KEY_CONFLICT   409
RESEARCH_NOT_COMPLETE   409
NOT_FOUND   404
VALIDATION_ERROR   422
RATE_LIMITED   429

Requests are limited per API key (not per IP - agents commonly share an address behind a company NAT or a hosting platform), enforced consistently regardless of which server process handles the request. Exceeding the limit returns 429.

Your first key includes a free trial of one standard objective. Metered operations: research (objectives, people/companies resolve) cost more than a single reasoning or DB lookup call (functions/resolve, verify, evidence, access resolve, compare targets). Check your balance any time via GET /v1/keys - like the other key-management endpoints above, this is authenticated with your account session, not the API key whose balance you’re checking.

A request that would take your balance negative is rejected with INSUFFICIENT_CREDITS before any research spend happens, never billed and then failed.

Keys are stored hashed (SHA-256), never in recoverable form. Every result you can access is scoped to your own account - a person, evidence item, or organisation is only visible if one of your own objectives surfaced it. Webhook deliveries are signed so you can verify they actually came from this service.

For current status per feature, see What’s live above - that table is the maintained source of truth; this changelog won’t duplicate it and risk drifting out of sync.