Lead Enrichment API

Enrich an existing GoodInbound contact with company details, a job title, LinkedIn information, and a research summary. Use the REST API from your backend or the enrich_contact tool through MCP.

Create or find a contact → Research public sources → Save details and notes
                                                   ↓
                                        Return the updated contact

Enrichment runs against a saved contact ID. It is not an email-only lookup endpoint, and it does not return a list of new prospects.

Before you start#

You need a project in a Pro workspace, a contact in that project, and a secret API key from MCP & APIs. Pro includes 500 contact enrichments per workspace per month, shared across projects. Free does not include enrichment.

The REST base URL is https://goodinbound.com. Send Authorization: Bearer gi_live_… from your server. A publishable Lead Screen key does not grant contact access.

1. Create or find the contact#

If the contact already exists, reuse its ID. You can search with GET /api/projects/:projectId/contacts?search=... or read a known record with GET /api/projects/:projectId/contacts/:contactId.

To create one, set GOODINBOUND_API_KEY and PROJECT_ID, then send:

curl --request POST "https://goodinbound.com/api/projects/$PROJECT_ID/contacts" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Alex Morgan",
    "email": "alex@example.com",
    "company": "Example Company",
    "companyWebsite": "https://example.com",
    "leadSource": "Website demo request"
  }'

Use your real contact's details in place of these illustrative values. name is required. Supplying known company and website details helps distinguish people with similar names. The response contains contact.id; use that value below.

2. Enrich the contact#

POST /api/projects/:projectId/contacts/:contactId/enrich

curl --request POST \
  "https://goodinbound.com/api/projects/$PROJECT_ID/contacts/$CONTACT_ID/enrich" \
  --header "Authorization: Bearer $GOODINBOUND_API_KEY"

No request body is needed. The request waits for research and persistence, then returns HTTP 200 with success: true and the updated contact. It does not return a background job ID.

Example response, showing selected fields only; actual findings vary:

{
  "success": true,
  "contact": {
    "id": "8e18db7e-4907-4d9d-aeca-bd44cae0e30d",
    "name": "Alex Morgan",
    "company": "Example Company",
    "companyWebsite": "https://example.com",
    "position": "Head of Operations",
    "companySize": "51–200 employees",
    "estimatedRevenue": null,
    "linkedinUrl": null,
    "notes": "— Research summary (2026-10-14) —\nResearch summary based on available public sources."
  }
}

What enrichment updates#

Non-empty findings can replace existing values in these structured fields. Missing findings do not blank existing values. Notes are appended rather than replaced, and the contact receives a research activity entry.

The full research record is saved at contact.metadata.workflow.research.byKey.enrichment. It includes executedAt, provider/model metadata, and result. The result includes source links, a summary, publicly listed emails and phone numbers, and additional company context when available. Research may also be available under metadata.workflow.research.latest, which changes when later research runs.

Publicly discovered emails and phone numbers stay in the research result; enrichment does not overwrite the contact's primary email or phone. Findings are AI-assisted research, not guaranteed verified contact data. Review sources before using estimates or inferred details in decisions.

Use enrichment through MCP#

Connect an OAuth-capable MCP client to:

https://goodinbound.com/api/mcp

Authorize the intended project with write access. Call enrich_contact with:

{
  "contactId": "8e18db7e-4907-4d9d-aeca-bd44cae0e30d"
}

The project comes from the OAuth grant; do not include projectId. The tool uses the same enrichment operation and allowance as REST. MCP uses OAuth, not REST API keys. See MCP Server.

Add it to your workflow#

Call enrichment after creating or selecting a contact, then use the returned record in your CRM sync or routing logic. For a GoodInbound workflow, the AI research action can research a contact and save structured findings. Its prompt is configurable; the dedicated enrichment endpoint uses a fixed research brief based on the contact's existing details.

Accepted form leads can also enter automatic enrichment on eligible plans. Check the contact's existing research timestamp before calling enrichment again if you want to avoid an unnecessary repeat.

Limits, retries, and errors#

Each successful enrichment call consumes one enrichment. Repeating the POST starts new research, can consume another unit, and appends another summary. This endpoint does not implement an Idempotency-Key contract. After a client timeout, read the contact and check its research timestamp before retrying.

REST management requests are limited to 120/minute per API key. MCP limits are 120 calls/minute per project and tool. Inspect current workspace entitlements with GET /api/projects/:projectId/entitlements.

Related: Lead Screening & Spam Protection API · Contacts and Tags · Authentication, Limits, and Errors.