> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time enrichment with webhooks

> Submit research via the API and process completed records in your app using company-researched and contact-researched webhooks.

Use webhooks when your product should react as soon as enrichment finishes — for example, updating a lead record in your database or kicking off an email sequence.

## Architecture

```mermaid theme={null}
sequenceDiagram
  participant App as Your backend
  participant API as Seamless API
  participant WH as Your webhook URL
  App->>API: POST /contacts/research
  API-->>App: requestIds
  API->>WH: POST contact-researched
  WH-->>API: 200 OK
```

## Setup checklist

1. Deploy an HTTPS endpoint (see [Webhooks guide](/receive-research-results-with-webhooks)).
2. In Seamless: **Settings → Webhooks** → create webhook → select `contact-researched` or `company-researched`.
3. Submit research via [Research contacts](/reference/researchcontacts) or [Research companies](/reference/researchcompanies).
4. Match incoming payloads to your stored `requestId` if you track jobs in a queue.

## Event types

| Event                | When it fires              |
| -------------------- | -------------------------- |
| `contact-researched` | Contact research completes |
| `company-researched` | Company research completes |

Validate the `x-seamless-webhook-secret` header on every request.

## Example company payload

When research completes, Seamless POSTs a JSON body with the enriched company object. Shape matches the public API **Company** schema (see [API Reference — Company Research](https://docs.seamless.ai/#tag/Company-Research)).

```json theme={null}
{
  "name": "Seamless.AI",
  "domain": "seamless.ai",
  "apiResearchId": "research-123",
  "phones": "+1-650-555-0100",
  "staffCountRange": "501 - 1,000",
  "revenueRange": "$1B+",
  "linkedInProfileUrl": "https://www.linkedin.com/company/seamless-ai/"
}
```

Contact webhooks return a **Contact** object with fields such as `fullname`, `email`, `phone`, `title`, and `company` — see [API Reference — Contact Research](https://docs.seamless.ai/#tag/Contact-Research).

## Runnable local test

1. Start the receiver from [Webhooks](/receive-research-results-with-webhooks).
2. Use [ngrok](https://ngrok.com/) or similar to expose `https://your-tunnel/webhooks/research-results`.
3. Register that URL in Settings → Webhooks.
4. Submit one research request and confirm your server logs the payload.

## Fallback

If a webhook delivery fails, poll with the saved `requestId` — see [Poll contact research](/reference/pollcontactsresearchresults).