---
title: "create"
description: "Create a contact, deal, action, note, call, or meeting in OnePageCRM."
canonical_url: https://developer.onepagecrm.com/mcp/tools/create/
source: Markdown mirror of https://developer.onepagecrm.com/mcp/tools/create/
---

`create` is the write tool for new records.

## Signature

```json
{
  "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`](/mcp/tools/describe/) once per
session to learn which fields are writable and which are required:

```json
{ "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`](/mcp/tools/context/).

## Example

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

Response:

```json
{
  "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`](/mcp/tools/describe/) returns
it:

```json
{
  "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.