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 (the 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; 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.

Example

{
  "entity": "contact",
  "data": {
    "first_name": "Jane",
    "last_name":  "Doe",
    "emails":     [{ "type": "work", "address": "jane.doe@acmesolar.example" }],
    "company":    "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":    "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.