create

create is the write tool for new records.

Signature

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "description": "One of: contact, deal, action, note, call, meeting."
    },
    "data": {
      "type": "object",
      "description": "Field values keyed by field name."
    }
  },
  "required": ["entity", "data"]
}

Both fields are required.

Supported entities

contact, deal, action, note, call, meeting. (Note the singular form — create takes one entity at a time.)

Companies are created indirectly: set company_name on a contact and the matching company record is created if it doesn’t already exist, with its company_id linked automatically.

Discovering valid fields

The agent should call describe once per session to learn which fields are writable and which are required:

{ "entity": "contact" }

The returned schema flags each field writable, and a top-level required_for_create rule states what a new record needs — for a contact, at least a last_name or a company_name; for a deal, a contact_id and a name. Anything not flagged writable: true is rejected.

For account-specific values (statuses, pipelines, users, tags, custom fields) the agent calls context.

Four of those take the name instead of the id, and describe lists the account’s own options as valid_values: status and lead_source on a contact, call_result on a call, reason_lost on a deal. "status": "Prospect" and "status_id": "prospect" write the same column, so send one or the other, not both. Names are matched case-insensitively. See update for the full rule.

Example

{
  "entity": "contact",
  "data": {
    "first_name":   "Jane",
    "last_name":    "Doe",
    "emails":       [{ "type": "work", "address": "jane.doe@acmesolar.example" }],
    "company_name": "Acme",
    "tags":         ["lead", "demo-requested"]
  }
}

Response:

{
  "entity": "contact",
  "id": "65f1b3c2a4d8e9f0c1234567",
  "data": {
    "id":           "65f1b3c2a4d8e9f0c1234567",
    "first_name":   "Jane",
    "last_name":    "Doe",
    "emails":       [{ "type": "work", "address": "jane.doe@acmesolar.example" }],
    "company_name": "Acme",
    "company_id":   "65f1...",
    "tags":         ["lead", "demo-requested"],
    "created_at":   "2025-..."
  }
}

Custom fields

Pass custom fields as a custom_fields object inside data, keyed by the field’s name exactly as describe returns it:

{
  "entity": "deal",
  "data": {
    "contact_id": "65f1b3c2a4d8e9f0c1234567",
    "name": "Enterprise deal",
    "amount": 5000,
    "custom_fields": { "Renewal Date": "2026-09-01", "Tier": "Gold" }
  }
}

Values are validated against each custom field’s type (dropdown values must match a configured choice, dates must be ISO 8601, and so on), and custom fields marked mandatory in the account settings are enforced on create.

Errors

• Validation errors — missing required fields, value out of range, invalid enum value, malformed email/phone. Returned as a structured error message naming the field and the problem.
• Unknown entity — the response includes the list of valid entity names; agents that send plurals ("contacts" instead of "contact") get a hint pointing at the singular form.
• Unknown fields — fields not present on the schema, or fields flagged read-only, are rejected.

Scope

crm — the write scope. crm.readonly is not sufficient.

All writes are attributed to the authenticated user. Records are created in that user’s account and respect their per-user permissions.