# Create business

`businesses.create`

Create a client business profile directly in one authorized workspace. Optionally save contacts and an initial private research note in the same transaction; an enrichment failure rolls back the complete save. Existing contact emails are linked without overwriting data. Set include_client_intake=true to also create or reuse intake, even when automatic intake is off. Unavailable intake setup preserves the Business and returns an explicit outcome. Read the returned intake question contract and current answers before populating supported facts. This does not fill answers, send outreach, invite clients, share intake, or create funding Projects. In-house attribution is assigned automatically. Retry the same request safely with the same client_request_id and identical input.

[Businesses guide](https://docs.staging.levr.ai/mcp/resources/businesses.md)

Availability depends on live discovery and your access to the record. Do not infer MCP calls from REST paths.

Operation: write. Required OAuth scopes: mcp.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "client_request_id": {
      "description": "Stable retry key for this creation request.",
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    },
    "contacts": {
      "description": "Public contacts to save and link atomically. Existing emails are reused without edits.",
      "items": {
        "additionalProperties": false,
        "anyOf": [
          {
            "required": [
              "email"
            ]
          },
          {
            "required": [
              "phone_number"
            ]
          }
        ],
        "properties": {
          "email": {
            "format": "email",
            "maxLength": 254,
            "minLength": 1,
            "type": "string"
          },
          "full_name": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "job_title": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "phone_number": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          }
        },
        "type": "object"
      },
      "maxItems": 10,
      "type": "array"
    },
    "include_client_intake": {
      "default": false,
      "description": "Explicitly include client intake using the source's published template even when automatic intake is off. Leaves source settings unchanged and sends no invitation. Inspect the returned client_intake_creation outcome; unavailable setup preserves the Business, contacts and note.",
      "type": "boolean"
    },
    "initial_note": {
      "description": "Private rich-text research note saved atomically: identity/location, sources, relevance, unknowns and requested drafts. Never put inferred facts into verified application answers.",
      "maxLength": 20000,
      "minLength": 1,
      "type": "string"
    },
    "name": {
      "description": "Business operating name.",
      "maxLength": 80,
      "minLength": 2,
      "pattern": "^[^%\\\\*|\"]+$",
      "type": "string"
    },
    "provider_slug": {
      "description": "Provider receiving the business. Copy provider_slug from providers.list; named slugs are valid.",
      "maxLength": 255,
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "provider_slug",
    "name",
    "client_request_id"
  ],
  "type": "object"
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "oneOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "properties": {
        "ok": {
          "const": true
        }
      },
      "required": [
        "data"
      ]
    },
    {
      "not": {
        "required": [
          "data"
        ]
      },
      "properties": {
        "ok": {
          "const": false
        }
      },
      "required": [
        "error"
      ]
    }
  ],
  "properties": {
    "data": {
      "additionalProperties": false,
      "properties": {
        "activation": {
          "additionalProperties": false,
          "properties": {
            "can_view": {
              "type": "boolean"
            },
            "next_offset": {
              "type": [
                "integer",
                "null"
              ]
            },
            "rows": {
              "items": {
                "additionalProperties": false,
                "properties": {
                  "application_count": {
                    "type": "integer"
                  },
                  "can_start_project": {
                    "type": "boolean"
                  },
                  "client_applications": {
                    "additionalProperties": false,
                    "properties": {
                      "incomplete": {
                        "type": "integer"
                      },
                      "submitted": {
                        "type": "integer"
                      },
                      "total": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  "incomplete_application_count": {
                    "type": "integer"
                  },
                  "last_client_activity_at": {
                    "format": "date-time",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "matching": {
                    "properties": {
                      "available_match_count": {
                        "type": "integer"
                      },
                      "client_enabled": {
                        "type": "boolean"
                      },
                      "is_running": {
                        "type": "boolean"
                      },
                      "is_stale": {
                        "type": "boolean"
                      },
                      "matched_count": {
                        "type": "integer"
                      },
                      "selected_count": {
                        "type": "integer"
                      },
                      "state": {
                        "type": "string"
                      }
                    },
                    "type": "object"
                  },
                  "progress": {
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "project": {
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "slug": {
                        "type": "string"
                      }
                    },
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "service_request": {
                    "properties": {
                      "ended_at": {
                        "format": "date-time",
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "name": {
                        "type": "string"
                      },
                      "slug": {
                        "type": "string"
                      }
                    },
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "target_amount": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "target_currency": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              "maxItems": 100,
              "type": "array"
            },
            "standalone_applications": {
              "additionalProperties": false,
              "properties": {
                "incomplete": {
                  "type": "integer"
                },
                "total": {
                  "type": "integer"
                }
              },
              "type": "object"
            }
          },
          "required": [
            "can_view",
            "rows",
            "next_offset"
          ],
          "type": "object"
        },
        "available_actions": {
          "description": "Permission-safe actions for collaborating with this client.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "frontend_link": {
                "type": "string"
              },
              "link_text": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            },
            "required": [
              "text",
              "link_text",
              "frontend_link"
            ],
            "type": "object"
          },
          "maxItems": 3,
          "type": "array"
        },
        "business": {
          "additionalProperties": false,
          "description": "Current provider-facing summary of this long-lived client business.",
          "properties": {
            "created_at": {
              "description": "When this business became available in this workspace.",
              "format": "date-time",
              "type": "string"
            },
            "frontend_link": {
              "description": "Authorized portal destination for this business.",
              "type": "string"
            },
            "id": {
              "description": "Stable Business id accepted by Business and Project tools.",
              "maxLength": 255,
              "minLength": 1,
              "type": "string"
            },
            "is_archived": {
              "description": "Whether this business is archived for the provider.",
              "type": "boolean"
            },
            "is_sample": {
              "description": "A fictional example for safe practice.",
              "type": "boolean"
            },
            "legal_name": {
              "description": "Legal name of the organization, maintained as shared business information.",
              "type": "string"
            },
            "name": {
              "description": "Provider-facing Business Hub display name. This uses the provider-owned name when set, then the operating name, then the legal name.",
              "type": "string"
            },
            "operating_name": {
              "anyOf": [
                {
                  "description": "Name the business operates or trades under, maintained as shared business information.",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Name the business operates or trades under, maintained as shared business information."
            },
            "provider": {
              "additionalProperties": false,
              "properties": {
                "name": {
                  "type": "string"
                },
                "provider_slug": {
                  "description": "Stable public identifier for the referenced resource.",
                  "maxLength": 255,
                  "minLength": 1,
                  "type": "string"
                }
              },
              "required": [
                "provider_slug",
                "name"
              ],
              "type": "object"
            },
            "revision": {
              "minimum": 0,
              "type": "integer"
            },
            "status": {
              "anyOf": [
                {
                  "additionalProperties": false,
                  "properties": {
                    "pipeline": {
                      "type": "string"
                    },
                    "stage": {
                      "type": "string"
                    },
                    "updated_at": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "required": [
                    "pipeline",
                    "stage",
                    "updated_at"
                  ],
                  "type": "object"
                },
                {
                  "type": "null"
                }
              ]
            },
            "updated_at": {
              "description": "When this provider-business relationship was last updated.",
              "format": "date-time",
              "type": "string"
            },
            "website": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "id",
            "revision",
            "name",
            "operating_name",
            "legal_name",
            "website",
            "is_archived",
            "provider",
            "created_at",
            "updated_at",
            "status",
            "frontend_link"
          ],
          "type": "object"
        },
        "client_collaboration": {
          "additionalProperties": false,
          "description": "Permission-aware ways the provider can collaborate with this client.",
          "properties": {
            "can_invite_business_members": {
              "type": "boolean"
            },
            "can_open_client_workspace": {
              "type": "boolean"
            },
            "can_share_client_intake": {
              "type": "boolean"
            },
            "can_view_business_members": {
              "type": "boolean"
            },
            "frontend_link": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "is_applicable": {
              "type": "boolean"
            }
          },
          "required": [
            "is_applicable",
            "can_open_client_workspace",
            "can_invite_business_members",
            "can_view_business_members",
            "can_share_client_intake",
            "frontend_link"
          ],
          "type": "object"
        },
        "client_intake_application": {
          "anyOf": [
            {
              "additionalProperties": false,
              "properties": {
                "id": {
                  "description": "Stable application_id accepted by client_intake_applications tools.",
                  "maxLength": 255,
                  "minLength": 1,
                  "type": "string"
                },
                "object": {
                  "const": "client_intake_application",
                  "type": "string"
                },
                "revision": {
                  "minimum": 0,
                  "type": "integer"
                },
                "status": {
                  "anyOf": [
                    {
                      "description": "Shared intake lifecycle status; independent of the business's internal pipeline stage.",
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Shared intake lifecycle status; independent of the business's internal pipeline stage."
                }
              },
              "required": [
                "id",
                "object",
                "status",
                "revision"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "client_intake_creation": {
          "additionalProperties": false,
          "description": "Present when include_client_intake=true. Created/existing intake is identified by client_intake_application.id. Unavailable preserves the Business; correct setup and use businesses.create_client_intake on that same Business. Creation retries return this original outcome.",
          "properties": {
            "code": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "message": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "status": {
              "enum": [
                "created",
                "existing",
                "unavailable"
              ],
              "type": "string"
            }
          },
          "required": [
            "status",
            "code",
            "message"
          ],
          "type": "object"
        },
        "client_membership": {
          "additionalProperties": false,
          "description": "Client participant access currently attached to the business workspace.",
          "properties": {
            "has_business_users": {
              "description": "Whether client participants have access to the business workspace.",
              "type": "boolean"
            },
            "member_count": {
              "description": "Client participants with access to the business workspace.",
              "minimum": 0,
              "type": "integer"
            }
          },
          "required": [
            "has_business_users",
            "member_count"
          ],
          "type": "object"
        },
        "has_unseen_completed_responses": {
          "description": "Whether completed application responses exist that the authenticated user has not marked reviewed. This field does not identify who supplied the response.",
          "type": "boolean"
        },
        "messages": {
          "additionalProperties": false,
          "description": "Current client-message signal and authorized conversation link.",
          "properties": {
            "frontend_link": {
              "type": "string"
            },
            "has_unread_client_messages": {
              "type": "boolean"
            },
            "latest_client_message": {
              "anyOf": [
                {
                  "maxLength": 500,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "has_unread_client_messages",
            "latest_client_message",
            "frontend_link"
          ],
          "type": "object"
        },
        "notes": {
          "description": "Most recent provider notes retained as business context.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "is_pinned": {
                "type": "boolean"
              },
              "text": {
                "maxLength": 2000,
                "type": "string"
              }
            },
            "required": [
              "text",
              "created_at",
              "is_pinned"
            ],
            "type": "object"
          },
          "maxItems": 3,
          "type": "array"
        },
        "notes_frontend_link": {
          "description": "Authorized link to manage notes for this business.",
          "type": "string"
        },
        "people": {
          "description": "People currently associated with the client business.",
          "items": {
            "additionalProperties": false,
            "properties": {
              "email": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "name": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "phone": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "name",
              "email",
              "phone"
            ],
            "type": "object"
          },
          "maxItems": 10,
          "type": "array"
        },
        "people_frontend_link": {
          "description": "Authorized link to manage people for this business.",
          "type": "string"
        }
      },
      "required": [
        "business",
        "client_membership",
        "client_intake_application",
        "client_collaboration",
        "messages",
        "has_unseen_completed_responses",
        "available_actions",
        "notes",
        "people",
        "notes_frontend_link",
        "people_frontend_link"
      ],
      "type": "object"
    },
    "error": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "details": {
          "additionalProperties": true,
          "description": "Optional bounded, agent-safe correction or recovery facts.",
          "type": "object"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "code",
        "message",
        "retryable"
      ],
      "type": "object"
    },
    "meta": {
      "additionalProperties": false,
      "properties": {
        "request_id": {
          "type": "string"
        }
      },
      "required": [
        "request_id"
      ],
      "type": "object"
    },
    "ok": {
      "description": "Whether the tool completed successfully.",
      "type": "boolean"
    }
  },
  "required": [
    "ok",
    "meta"
  ],
  "type": "object"
}
```

Check the result, then read the affected record to confirm your change.