Organizations

An organization is a company or other body that your contacts work for. Carom creates organizations from the email domains it sees in correspondence and links each contact to one through an employment. Use this resource to read an organization with its people and recent activity, correct its name or description, and create organizations Carom hasn’t found yet.

Organizations belong to the whole account. Every user can see every organization, and anyone who can see one can edit it; only account admins can delete one. Thread and file counts, and the people listed at an organization, are the exception: they cover only correspondence and contacts visible to your key.

#The organization object

Returned by every organization endpoint. Retrieving a single organization adds its upcoming events, activity counts, and timeline.

Attributes

  • idstring · uuid

    Unique identifier for the organization.

  • namestring · nullable

    Display name. For an organization Carom created from a domain, this starts as the domain and is replaced when Carom learns the real name.

  • name_sourcestring · nullable

    Who set name. auto: Carom used the domain when it created the organization. enrichment: Carom filled it in from the organization’s website. user: a person set it, in the app or through the API. Null for a name set before Carom recorded its source. Carom replaces only a name that is empty, auto, or enrichment.

    autoenrichmentuser
  • descriptionstring · nullable

    A short account of what the organization does, written by your team or filled in by Carom from the organization’s website.

  • description_sourcestring · nullable

    Who set description. enrichment: Carom filled it in from the organization’s website. user: a person set it. Null when there is no description, or for one set before Carom recorded its source. Carom replaces only a description that is empty or enrichment.

    enrichmentuser
  • domainstring · nullable

    The organization’s email and web domain, such as wildgrove.example, in lowercase. Unique within the account.

  • contact_countinteger · nullable

    Number of contacts employed at the organization.

  • thread_countinteger · nullable

    Number of threads with people at the organization, counted across the mailboxes whose statistics are visible to your key (see statistics visible to your key).

  • file_countinteger · nullable

    Number of files exchanged with people at the organization, counted the same way.

  • pinnedboolean · nullable

    Whether your key’s user has pinned this organization.

  • logoobject · nullable

    The organization’s logo, with a source_url you can display directly and the original file_name.

  • tasksarray of tasks · nullable

    Open tasks attached to the organization. Retrieve an organization includes up to five.

  • commentsarray of comments · nullable

    Comments your team has left on the organization. For comments on its people and deals as well, use Retrieve an organization’s discussion.

  • contactsarray of contacts · nullable

    People employed at the organization who are visible to your key, not counting mailing lists and notification senders. Present on Retrieve and Update responses; null elsewhere.

  • tagsarray of tags · nullable

    Tags applied to this organization.

The organization object 
{
  "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
  "name": "Wildgrove Property Management",
  "name_source": "enrichment",
  "description": "Manages residential and mixed-use buildings in the East Bay.",
  "description_source": "user",
  "domain": "wildgrove.example",
  "contact_count": 6,
  "thread_count": 58,
  "file_count": 12,
  "pinned": true,
  "logo": null,
  "tasks": [],
  "comments": [],
  "contacts": null,
  "tags": [
    {
      "id": "0f1e2d3c-4b5a-4968-8776-655443322110",
      "name": "Customer",
      "color": "#66b185",
      …
    }
  ]
}
get/organizations Read key

#List organizations

Returns the account’s organizations, 50 per page, alphabetically by name unless you choose another sort. Filter by a search query, by tags, or to the ones you’ve pinned, and page through the result with a cursor.

Query parameters

  • querystring

    Match against names, domains, and descriptions. Up to 500 characters.

  • slicestring

    pinned returns only organizations your key’s user has pinned. Any other value is ignored.

    pinned
  • sortstringdefault name

    Field to sort by. An unrecognized value falls back to name.

    namecontact_countthread_countfile_count
  • orderstring

    Defaults to asc for name and desc for the counts. Any other value uses the default.

    ascdesc
  • tagsstring

    Comma-separated tag ids, at most 50.

  • tag_operatorstringdefault any

    Whether an organization must carry any of the given tags, or all of them.

    anyall
  • next_cursorstring

    Opaque token from the previous page’s page_info.next_cursor. Omit to start from the beginning. Send the same sort and order as on the first page. See Cursor pagination.

Returns

  • collectionobject

    A page of organizations and the cursor to the next one.

    Show 3 child attributesHide child attributes
    • recordsarray of organizations

      Up to 50 organizations in the requested order.

    • page_infopage info

      Where this page sits in the full list. Pass next_cursor back to fetch the next page while has_more_after is true.

    • sort, order, slice_key, filtersnullable

      The sort, order, and slice you sent, and your query, tags, and tag_operator as filters, echoed back. Null when you sent none. See the cursor collection.

Errors

  • 400invalid_requestA parameter is malformed, for example a query over 500 characters or a tag id that isn’t a UUID.
  • 400invalid_cursorThe cursor is unreadable, or came from another list or sort.
  • 400unsupported_cursor_directionThis list pages forward only.
get/organizations 
curl "https://api.carom.io/organizations?sort=thread_count&tags=0f1e2d3c-4b5a-4968-8776-655443322110" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "collection": {
    "records": [
      {
        "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
        "name": "Wildgrove Property Management",
        "domain": "wildgrove.example",
        "contact_count": 6,
        "thread_count": 58,
        …
      },
      {
        "id": "2d7f4b1e-8c3a-4e5d-9b6f-1a0c3e7d5b92",
        "name": "Halvorsen Freight",
        "domain": "halvorsenfreight.example",
        "contact_count": 3,
        "thread_count": 21,
        …
      }
    ],
    "page_info": {
      "limit": 50,
      "next_cursor": "Pz5Nc8Rt1Wq7Lk3Vb9Hx2Gm6Jd4Sy0Fa8Tu1Ke",
      "prev_cursor": null,
      "has_more_after": true,
      "has_more_before": false
    },
    "sort": "thread_count",
    "filters": {
      "tags": "0f1e2d3c-4b5a-4968-8776-655443322110"
    }
  }
}
post/organizations Write key

#Create an organization

Creates an organization. If you give a domain and the account already has an organization with that domain, Carom returns the existing organization unchanged, with the same status, instead of creating a second one. Compare the returned name and description with what you sent, and update it if you meant to change it.

Request body application/json

  • organizationobjectrequired
    Show 4 child attributesHide child attributes
    • namestringrequired
    • descriptionstring
    • domainstring

      Such as wildgrove.example, without a scheme or path. Carom trims it and stores it in lowercase, so matching an existing domain ignores case. A blank domain is stored as null.

    • logo_upload_idstring · uuid

      Id of an image you uploaded to use as the logo.

Returns

The new or existing organization object, wrapped in organization.

Errors

  • 400invalid_requestA field failed validation, for example a missing name or a logo_upload_id that isn’t your image upload. error.fields says which.
post/organizations 
curl https://api.carom.io/organizations \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Halvorsen Freight",
      "domain": "halvorsenfreight.example",
      "description": "Regional trucking and warehousing in the Pacific Northwest."
    }
  }'
Response200 
{
  "organization": {
    "id": "2d7f4b1e-8c3a-4e5d-9b6f-1a0c3e7d5b92",
    "name": "Halvorsen Freight",
    "description": "Regional trucking and warehousing in the Pacific Northwest.",
    "domain": "halvorsenfreight.example",
    "contact_count": 0,
    "thread_count": 0,
    "file_count": 0,
    "pinned": false,
    "logo": null,
    …
  }
}
get/organizations/{id} Read key

#Retrieve an organization

Returns a single organization with the people who work there, up to five open tasks, up to three upcoming events, and its timeline of recent activity.

Path parameters

  • idstring · uuidrequired

    The organization’s id.

Returns

The organization object, wrapped in organization, with contacts filled in and these additional attributes.

  • countsobject

    Full-set totals behind the tasks and events previews.

    Show 2 child attributesHide child attributes
    • open_tasksinteger

      Open tasks attached to the organization that are visible to your key.

    • upcoming_eventsinteger

      Events with the organization’s people that start today or later in the time zone of your key’s user.

  • eventsarray of calendar events

    Up to three upcoming events, soonest first.

  • timelineobject · nullable

    The organization’s recent activity, as an object with an items array of timeline items.

Errors

  • 404record_not_foundNo organization with that id is visible to your key, or the id isn’t a UUID.
get/organizations/{id} 
curl https://api.carom.io/organizations/6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "organization": {
    "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
    "name": "Wildgrove Property Management",
    …
    "contacts": [
      {
        "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
        "name": "Priya Natarajan",
        …
      }
    ],
    "counts": {
      "open_tasks": 2,
      "upcoming_events": 1
    },
    "events": [
      {
        "id": "b8c9d0e1-f2a3-4b4c-9d5e-6f7a8b9c0d12",
        "name": "Wildgrove renewal review",
        …
      }
    ],
    "timeline": {
      "items": [
        …
      ]
    }
  }
}
patch/organizations/{id} Write key

#Update an organization

Changes the fields you send and leaves the rest alone. Every field is optional. A name or description you change is marked user in name_source or description_source, so Carom doesn’t replace it with details it later finds on the organization’s website.

Path parameters

  • idstring · uuidrequired

Request body application/json

  • organizationobjectrequired

    Any of the attributes accepted by Create an organization. name can’t be empty. Send "description": null to clear the description, and "logo_upload_id": null to remove the logo; omit a field to leave it as it is.

Returns

The updated organization object, wrapped in organization, with contacts filled in.

Errors

  • 400invalid_requestA field failed validation, for example an empty name. error.fields says which.
  • 404record_not_foundNo organization with that id is visible to your key.
patch/organizations/{id} 
curl -X PATCH https://api.carom.io/organizations/6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "description": "Manages residential and mixed-use buildings in the East Bay and Sacramento."
    }
  }'
Response200 
{
  "organization": {
    "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
    "name": "Wildgrove Property Management",
    "description": "Manages residential and mixed-use buildings in the East Bay and Sacramento.",
    "description_source": "user",
    "domain": "wildgrove.example",
    …
  }
}
delete/organizations/{id} Write key

#Delete an organization

Permanently deletes an organization. Only an account admin can delete one.

The people who worked there stay, but their employments at the organization are deleted. The organization’s logo, the tasks attached to it, the comments on it, and its pins and shares are deleted with it, and it is removed from its tags and spaces. Pending proposals about the organization or its tasks expire.

An organization that is the counterparty of a deal can’t be deleted, including deals in pipelines your key can’t see. Delete the deal or change its counterparty first.

Path parameters

  • idstring · uuidrequired

Returns

An empty response with status 204.

Errors

  • 403permission_deniedYour key’s user isn’t an account admin.
  • 404record_not_foundNo organization with that id is visible to your key.
  • 409organization_has_dealsThe organization is the counterparty of at least one deal. Nothing was deleted.
delete/organizations/{id} 
curl -X DELETE https://api.carom.io/organizations/2d7f4b1e-8c3a-4e5d-9b6f-1a0c3e7d5b92 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response204 
No content
get/organizations/count Read key

#Count organizations

Counts the organizations that List organizations would return for the same filters, without fetching them. Counting stops at cap when you give one, which keeps the call fast on large accounts.

Query parameters

  • query, slice, tags, tag_operator

    As on List organizations.

  • capinteger

    Stop counting at this many. When more organizations match, total equals cap and exact is false. A value of 0 or less is ignored.

Returns

  • countcount
    Show 4 child attributesHide child attributes
    • totalinteger
    • exactboolean

      False when counting stopped at cap.

    • cappedboolean
    • capinteger · nullable

      The cap that applied. Null when you sent none, or sent zero or a negative number.

Errors

  • 400invalid_requestA parameter is malformed, for example a tag id that isn’t a UUID.
get/organizations/count 
curl "https://api.carom.io/organizations/count?query=freight&cap=1000" \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "count": {
    "total": 14,
    "exact": true,
    "capped": false,
    "cap": 1000
  }
}
get/organizations/{id}/discussion Read key

#Retrieve an organization’s discussion

Returns the comments your team has left on this organization, on the people who work there, and on the organization’s deals, grouped into scopes. Comments are internal; the organization never sees them.

The first scope is the organization itself and is always present. The people and deals scopes appear only when at least one record in them has a comment, and include only records visible to your key.

Path parameters

  • idstring · uuidrequired

Returns

  • discussionobject
    Show 1 child attributeHide child attributes
    • scopesarray of objects

      One entry per group of records, in display order.

      Show 6 child attributesHide child attributes
      • keystring
        organizationpeopledeals
      • labelstring

        A heading for the scope, such as This organization.

      • unitstring

        What the scope’s records are: organizations, people, or deals.

      • primaryboolean

        True for the organization’s own scope.

      • total_commentsinteger
      • recordsarray of objects

        The commented records in the scope, most recently discussed first.

        Show 6 child attributesHide child attributes
        • keystring

          The record type and id, joined by a hyphen.

        • record_typestring
          organizationcontactdeal
        • record_idstring · uuid
        • namestring · nullable
        • total_commentsinteger
        • commentsarray of comments

          Oldest first.

Errors

  • 404record_not_foundNo organization with that id is visible to your key.
get/organizations/{id}/discussion 
curl https://api.carom.io/organizations/6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3/discussion \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "discussion": {
    "scopes": [
      {
        "key": "organization",
        "label": "This organization",
        "unit": "organizations",
        "primary": true,
        "total_comments": 0,
        "records": [
          {
            "key": "organization-6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
            "record_type": "organization",
            "record_id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
            "name": "Wildgrove Property Management",
            "total_comments": 0,
            "comments": []
          }
        ]
      },
      {
        "key": "people",
        "label": "People",
        "unit": "people",
        "primary": false,
        "total_comments": 1,
        "records": [
          {
            "key": "contact-1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "record_type": "contact",
            "record_id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "name": "Priya Natarajan",
            "total_comments": 1,
            "comments": [
              {
                "id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",
                "html_content": "<p>Priya needs the renewal numbers before the 15th. She's out the week after.</p>",
                "user_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
                "created_at": "2026-09-03T18:44:12.618Z",
                …
              }
            ]
          }
        ]
      }
    ]
  }
}