Skip to main content
POST
/
v1
/
contacts
Create Contact
curl --request POST \
  --url https://api.example.com/v1/contacts \
  --header 'Content-Type: application/json' \
  --data '
{
  "full_name": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "job_title": "<string>",
  "company": "<string>",
  "related_company_id": "<string>",
  "linkedin_url": "<string>",
  "priority": {},
  "tags": [
    {}
  ],
  "custom_fields": {},
  "created_date": "<string>"
}
'
{
  "data": {
    "id": "<string>",
    "first_name": "<string>",
    "last_name": "<string>",
    "full_name": "<string>",
    "email": "<string>",
    "priority": 123,
    "created_date": "<string>"
  }
}

​
Request

​
Headers

Authorization: Bearer wbk_your_api_key_here
Content-Type: application/json

​
Body Parameters

Name handling: Send any of full_name, first_name + last_name, or just an email. The API splits / composes / derives the missing pieces. It also understands the "Last, First" format.
​
full_name
string
Contact’s full name. If only this is given, the API splits on the last whitespace (e.g. "Hans Müller" → first=Hans, last=Müller). Accepts the "Last, First" format (e.g. "Müller, Hans").
​
first_name
string
Contact’s first name. Composed into full_name if full_name isn’t provided.
​
last_name
string
Contact’s last name.
​
email
string
Email address. Used for duplicate detection and, as a last resort, to derive a name (e.g. hans.mueller@x.de → first=Hans, last=Mueller) when no name is given.
​
phone
string
Phone number with country code
​
job_title
string
Job title or position
​
company
string
Company or organization name
​
related_company_id
string
UUID of an existing Company to link this contact to. Also accepts the legacy company_id key.
​
linkedin_url
string
LinkedIn profile URL
​
priority
string | number
Either "high" / "medium" / "low" or an integer (1/2/3).
​
tags
array
Array of tag strings for categorization
​
custom_fields
object
Arbitrary JSON object preserved alongside the contact — ideal for domain-specific columns from imported CSVs (e.g. matter numbers, jurisdiction codes).
​
created_date
string
Optional ISO 8601 timestamp. Honored verbatim if it’s within the last 5 years and no more than 24 h in the future; otherwise the server now() is used. Never null.

​
Response

​
data
object
The created contact object.
curl -X POST \
  https://data.leadlex.com/functions/v1/api-gateway/v1/contacts \
  -H "Authorization: Bearer wbk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Müller, Hans",
    "email": "hans@roche.com",
    "job_title": "IP Partner",
    "company": "Roche AG"
  }'

​
Example Response

{
  "data": {
    "id": "789e0123-e45b-67c8-a901-234567890abc",
    "first_name": "Hans",
    "last_name": "Müller",
    "full_name": "Hans Müller",
    "email": "hans@roche.com",
    "priority": null,
    "created_date": "2026-04-21T14:30:00.000Z"
  }
}

​
Validation

At least one of first_name, last_name, full_name, or email must be provided. If none are present the API returns validation_error.

​
Name derivation rules

Applied in order; the first rule that yields a name wins:
  1. "Last, First" format — if full_name contains a comma and first/last are empty, it’s split into last / first.
  2. Split full_name — when full_name is given but first_name / last_name are empty, it’s split on the last whitespace. “Jean-Claude van Damme” → first=Jean-Claude van, last=Damme.
  3. Compose full_name — when first_name / last_name are given but full_name is empty.
  4. Derive from email — local part is split on ._-+ into Title Case tokens.

​
Duplicate Detection

The API checks for duplicates by:
  • Exact email match (case-insensitive)
  • Full-name ILIKE match
If a duplicate is found the Lexi agent prompts for confirmation. The REST endpoint still creates the contact (pass force_create: false on the agent tool to suppress).

​
Errors

StatusCodeDescription
400validation_errorNo name or email provided
401invalid_keyInvalid API key
403insufficient_permissionsMissing contacts:write permission
429rate_limitedRate limit exceeded

​
Example Validation Error

{
  "error": {
    "code": "validation_error",
    "message": "A name (first_name, last_name, or full_name) or email is required"
  }
}