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

# Webhooks import

> This article explains how to use webhook-based imports to send real-time contact and company data from external tools—like CRMs, signup forms, or internal systems—directly into FirstQuadrant. It covers how to locate your unique webhook URL, the expected data format, field-level documentation, response handling, and integration best practices. You’ll also find examples for using webhooks via Zapier or custom applications. This is the most flexible way to programmatically sync high-quality data into your workspace and trigger AI workflows instantly. 

## Overview

FirstQuadrant supports **webhook-based imports** as a powerful way to send contact and company data directly into your workspace in real time. This is particularly useful for integrating external systems such as CRMs, marketing platforms, signup forms, or internal tools with FirstQuadrant.

Webhooks allow you to push data into FirstQuadrant automatically whenever a new contact is created or updated externally.

## Where to find your webhook

Navigate to the **Imports** section in your workspace. From there:

* Click **new import**
* You will be provided with a **webhook URL** specific to that import.
* This URL includes a secure hash and should be kept private.

FirstQuadrant provides webhooks as a powerful way to automatically import contacts and companies from external systems. Webhooks allow you to send real-time data to FirstQuadrant whenever new contacts are created in your CRM, marketing automation platform, or any other system.

## Webhook URL format

Your webhook URL will follow this format:

```
https://api.us.firstquadrant.ai/v5/imports/{importId}/trigger/{hash}
```

Where:

* `{importId}` is your unique import identifier
* `{hash}` is a secure hash that validates webhook requests

## Making webhook requests

Send a `POST` request to your webhook URL with a JSON body containing contact and company data. The minimum required structure is:

```json theme={null}
{
  "contact": {
    "email": "jane.doe@example.com"
  }
}
```

### Complete data structure

You can provide comprehensive contact and company information using the following schema:

```json theme={null}
{
  "contact": {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "nickname": "Jane",
    "bio": "Senior Sales Manager at Acme Corp",
    "avatar": "https://example.com/avatar.jpg",
    "website": "https://janedoe.com",
    "domain": "janedoe.com",
    "location": "San Francisco, CA",
    "timeZone": "America/Los_Angeles",
    "facebookHandle": "janedoe",
    "gitHubHandle": "janedoe",
    "instagramHandle": "janedoe",
    "linkedInHandle": "jane-doe",
    "xHandle": "janedoe",
    "externalIdApollo": "apollo_123",
    "note": "Met at conference, interested in enterprise plan"
  },
  "employment": {
    "title": "Senior Sales Manager",
    "seniority": "SENIOR",
    "history": [
      {
        "current": true,
        "start": "2022-01",
        "organization": "Acme Corporation",
        "title": "Senior Sales Manager"
      },
      {
        "current": false,
        "start": "2020-03",
        "end": "2021-12",
        "organization": "Previous Company",
        "title": "Sales Manager"
      }
    ]
  },
  "company": {
    "name": "Acme Corporation",
    "nickname": "Acme",
    "bio": "Leading provider of innovative solutions",
    "subtitle": "Innovation at its finest",
    "avatar": "https://example.com/logo.png",
    "website": "https://acme.com",
    "domain": "acme.com",
    "location": "San Francisco, CA",
    "timeZone": "America/Los_Angeles",
    "facebookHandle": "acmecorp",
    "gitHubHandle": "acmecorp",
    "instagramHandle": "acmecorp",
    "linkedInHandle": "acme-corporation",
    "xHandle": "acmecorp",
    "annualRevenue": "10000000",
    "employeesCount": 250,
    "foundedYear": 2015,
    "fundingStage": "Series B",
    "fundingTotal": "25000000",
    "retailLocationsCount": 5,
    "ticker": "ACME",
    "industries": ["Technology", "SaaS"],
    "languages": ["English", "Spanish"],
    "stack": ["React", "Node.js", "PostgreSQL"],
    "tags": ["enterprise", "b2b"],
    "externalIdApollo": "apollo_company_456"
  }
}
```

### Field descriptions

#### Contact fields

* **email** (string, nullable): Primary email address
* **name** (string, nullable): Full name of the contact
* **nickname** (string, nullable): Common or preferred name
* **bio** (string, nullable): Description or bio from social media
* **avatar** (string, nullable): URL to profile picture
* **website** (string, nullable): Personal website URL
* **domain** (string, nullable): Domain of personal website
* **location** (string, nullable): Geographic location
* **timeZone** (string, nullable): Time zone (e.g., "America/Los\_Angeles")
* **social handles**: Facebook, GitHub, Instagram, LinkedIn, X (Twitter) handles
* **externalIdApollo** (string, nullable): External ID from Apollo.io
* **note** (string, nullable): Additional context or notes

#### Employment fields

* **title** (string, nullable): Job title
* **seniority** (string, nullable): Seniority level (JUNIOR, MID, SENIOR, EXECUTIVE)
* **history** (array): Work history with start/end dates, organization, and title

#### Company fields

* **name** (string, nullable): Legal company name
* **nickname** (string, nullable): Common or brand name
* **bio** (string, nullable): Company description
* **subtitle** (string, nullable): Short company description
* **avatar** (string, nullable): Company logo URL
* **website** (string, nullable): Company website URL
* **domain** (string, nullable): Company domain
* **location** (string, nullable): Company headquarters location
* **timeZone** (string, nullable): Company time zone
* **social handles**: Company social media handles
* **financial data**: Revenue, employee count, funding information
* **industries** (array): Industry categories
* **languages** (array): Languages supported
* **stack** (array): Technology stack
* **tags** (array): Custom tags
* **externalIdApollo** (string, nullable): External ID from Apollo.io

## Response format

Successful webhook requests return a JSON response with the created row data:

```json theme={null}
{
  "id": "row_123456789",
  "object": "row",
  "status": "PENDING",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

## Error handling

Webhook requests may return the following HTTP status codes:

* **200**: Success - Contact imported successfully
* **400**: Bad Request - Invalid data format
* **404**: Not Found - Invalid webhook URL or hash
* **429**: Rate Limited - Too many requests
* **500**: Internal Server Error - Server error

## Best practices

### Data quality

* Always provide an email address when possible
* Use consistent formatting for names and company information
* Include relevant social media handles for better enrichment
* Add notes to provide context about the contact

### Rate limiting

* Implement exponential backoff for failed requests
* Don't send duplicate data for the same contact
* Batch multiple contacts when possible

### Security

* Keep your webhook URL and hash secure
* Use HTTPS for all webhook requests
* Validate data before sending to FirstQuadrant

### Monitoring

* Monitor webhook response codes
* Set up alerts for failed webhook requests
* Track the number of contacts imported via webhooks

## Integration examples

### Zapier integration

1. Create a new Zap with your trigger app
2. Add FirstQuadrant as an action
3. Use the webhook URL as the endpoint
4. Map your trigger data to the webhook payload

### Custom application

```javascript theme={null}
const webhookUrl = "https://api.us.firstquadrant.ai/v5/imports/imp_123/trigger/fqw_abc123";

const contactData = {
  contact: {
    email: "new.contact@example.com",
    name: "John Smith",
    note: "Imported from CRM system",
  },
  company: {
    name: "Example Corp",
    website: "https://example.com",
  },
};

fetch(webhookUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify(contactData),
})
  .then((response) => response.json())
  .then((data) => console.log("Contact imported:", data))
  .catch((error) => console.error("Error:", error));
```

## Additional notes

* Notes added via webhook are treated the same way as manual notes.
* These notes are run through AI reasoning to guide next-step decisions in conversation workflows.
* To fine-tune how notes are handled, visit **[Fine-Tune Settings](/product-manual/fine-tuning/fine-tuning-overview)** in your workspace.