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.
Create and update
{
"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: 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.
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.