Create a new contact in your Dalil AI workspace. Optionally trigger AI enrichment to automatically fill in missing fields.

Creates a new contact. At minimum, provide either email or linkedin_url. Dalil AI can enrich the contact automatically if you pass enrich: true.

Request Body

Field	Type	Required	Description
`email`	string	Conditional*	Contact's email address
`linkedin_url`	string	Conditional*	LinkedIn profile URL
`first_name`	string	No	First name
`last_name`	string	No	Last name
`title`	string	No	Job title
`company`	string	No	Company name
`phone`	string	No	Phone number
`tags`	string[]	No	Array of tag names to apply
`owner_id`	string	No	Assign to a specific user (defaults to API key owner)
`enrich`	boolean	No	Trigger AI enrichment (default: false)
`custom_fields`	object	No	Any key-value pairs for custom fields

*At least one of email or linkedin_url is required.

Request

curl -X POST https://api.usedalil.ai/v1/contacts \
  -H "Authorization: Bearer dalil_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sarah@acmecorp.com",
    "first_name": "Sarah",
    "last_name": "Chen",
    "title": "VP of Sales",
    "company": "Acme Corp",
    "tags": ["outbound-q2", "series-b"],
    "enrich": true
  }'

When enrich: true, the contact is created immediately and enrichment happens asynchronously. The enrichment_status field will change from pending to complete (or failed) within 30 seconds. Use webhooks to be notified when enrichment completes.

Handling Duplicates

By default, if a contact with the same email already exists, the API returns a 409 Conflict error. To merge instead:

{
  "email": "sarah@acmecorp.com",
  "on_conflict": "merge"
}

With "on_conflict": "merge", existing fields are preserved and only new fields are updated.

Code Examples

JavaScript

import Dalil from '@dalilai/sdk';

const client = new Dalil({ apiKey: process.env.DALIL_API_KEY });

const contact = await client.contacts.create({
  email: 'sarah@acmecorp.com',
  firstName: 'Sarah',
  lastName: 'Chen',
  title: 'VP of Sales',
  company: 'Acme Corp',
  tags: ['outbound-q2'],
  enrich: true,
});

console.log('Created:', contact.id);

Python

import dalilai

client = dalilai.Client(api_key=os.environ["DALIL_API_KEY"])

contact = client.contacts.create(
    email="sarah@acmecorp.com",
    first_name="Sarah",
    last_name="Chen",
    title="VP of Sales",
    company="Acme Corp",
    tags=["outbound-q2"],
    enrich=True,
)

print(f"Created: {contact.id}")

Error Responses

Code	Message	Description
`400 Bad Request`	`email_or_linkedin_required`	Neither email nor LinkedIn URL provided
`409 Conflict`	`contact_already_exists`	Contact with this email exists; use `on_conflict`
`422 Unprocessable Entity`	`invalid_email`	Email format is invalid

Create Contact