# Organisations

> Keep companies and affiliations connected.

## A shared identity for a company

An organisation represents a company, institution, or other group. Contacts remain independent people; affiliations connect them to organisations with a role and optional dates.

Use `organisations_search` before creating a record. A literal name or ID fragment goes in `query`; an exact case-insensitive website hostname goes in `domain`. Filter by `project_id` for organisations participating in that project. Optional `tag`, scalar `custom_fields`, archive, and pagination filters work as described in the [tool reference](/docs/mcp-tools).

## Create and update

```json
{
  "name": "Example Studio",
  "website": "https://example.com",
  "description": "Our research partner.",
  "tags": ["partner"],
  "idempotency_key": "example-studio-001"
}
```

Call `organisations_create`. Only `name` and `idempotency_key` are required. Optional fields are `website`, `description`, `tags`, `external_references`, and registered `custom_fields`. Orbit derives a lowercase domain from the HTTP(S) website; it never fetches the URL. The derived domain is not directly writable.

A matching active name or domain produces `ambiguous_match` with candidate IDs. Review them before setting `allow_duplicate: true` for a distinct organisation. No automatic merge occurs.

`organisations_get` takes `id`. `organisations_update` takes `id`, `expected_revision`, `idempotency_key`, and `changes` or `remove_custom_fields`. Use the same [patch conventions as contacts](/docs/contacts#update-a-contact): omitted fields persist, arrays replace, optional text accepts null, and custom-field keys are patched.

## Archive and restore

`organisations_archive` and `organisations_restore` take `id`, `expected_revision`, and `idempotency_key`. Archive retains history and links. Archived organisations are hidden by default and cannot receive new links or edits until restored.

## Link people and context

Use `affiliations_set` to link a contact, with a role and optional employment dates. Organisations can also participate in projects, receive linked activity, and be linked to tasks. Every endpoint of a new relationship must be active and in the same workspace. See [Relationships](/docs/relationships).

## Choose result order

Search accepts `sort`: `name`, `created_at`, or `updated_at`, with `direction`: `asc` (default) or `desc`. The first field is the default. ID ascending breaks ties; nullable dates sort last. Only these field names are accepted.