Semantics
Creates a contact record with name, email, optional phone and company. If a contact with the same email already exists on this tenant, returns that contact unchanged (idempotent on email). Optionally seeds a deal under the contact when `seed_deal` is true.
Invariants
- Idempotent on `(tenant, email)`. Repeat calls return the same contact_id and do not create duplicates.
- Email is required and must be a syntactically valid address.
- Returned `contact_id` is stable and addressable from `log_activity` going forward.
When to use
When a new prospect or customer has surfaced and is not yet in the CRM. Always call this before `log_activity` if the contact's email is unknown to the tenant.
Input schema
{
"type": "object",
"required": [
"name",
"email"
],
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"email": {
"type": "string",
"format": "email"
},
"phone": {
"type": "string"
},
"source": {
"type": "string",
"description": "Where the contact came from (e.g. 'website-form', 'agent-claude', 'referral')."
},
"company": {
"type": "string"
},
"seed_deal": {
"type": "boolean",
"description": "If true, also creates a deal under the contact in stage 'new'."
},
"agent_vendor": {
"type": "string"
}
},
"additionalProperties": false
}Output schema
{
"type": "object",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean"
},
"error": {
"enum": [
"invalid_email",
"invalid_input"
],
"type": "string"
},
"created": {
"type": "boolean",
"description": "True if newly created, false if returned an existing contact (idempotent hit)."
},
"deal_id": {
"type": "string"
},
"contact_id": {
"type": "string"
}
}
}