Shares

A share gives a colleague, or a group of colleagues, access to a record they couldn’t otherwise see: a thread from your mailbox, a file, or a personal contact or organization. Use this resource to share those records and to change or revoke the shares your key’s user made.

Each recipient gets a share of their own, which only the user who created it can change or revoke. A share’s scope decides how much it grants. Accepting a share request creates an interactions share.

To find a share’s id, retrieve the shared record: Retrieve a thread, Retrieve a file, and Retrieve a contact return the record’s shares. Organizations don’t return their shares.

#The share object

One recipient’s access to one record. Exactly one of user and group is set.

Attributes

  • idstring · uuid

    Unique identifier for the share.

  • sharer_idstring · uuid

    The user who created the share. Only this user can change or delete it.

  • useruser · nullable

    The recipient, when the share is to a single user.

  • groupgroup · nullable

    The recipient, when the share is to a group, with its users. Every member of the group has the access.

  • scopestring · nullable

    How much the share grants. Null when the share was created without a scope, which grants the same access as ongoing. Under any scope, a thread share covers only messages in mailboxes the sharer can currently read; if the sharer loses access to a mailbox, its messages stop being shared.

    Show 3 valuesHide values
    • ongoing

      Shares the record with no cutoff, on every record type. On a thread, messages that arrive later are shared too.

    • to_date

      Stops at share_through.

      On a thread, the recipient sees only the messages sent at or before share_through, and their attachments.

      On a file, the recipient gets the file, and sees only the messages it was attached to that were sent by then.

      On a contact or organization, the same as ongoing.

    • interactions

      Contacts and organizations only.

      On a contact, shares the contact, plus the messages between the sharer’s mailboxes and the contact’s email addresses, as those addresses stood when the share was made.

      On an organization, the same as ongoing.

  • share_throughstring · date-time · nullable

    The cutoff for a to_date share. Messages sent after it aren’t shared. Other scopes ignore it.

  • notestring · nullable

    A message from the sharer to the recipient.

  • created_atstring · date-time · nullable
The share object 
{
  "id": "f4e3d2c1-b0a9-4876-9543-210fedcba987",
  "sharer_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
  "user": {
    "id": "4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84",
    "first_name": "Jordan",
    "last_name": "Reyes",
    "email_address": "jordan@harborline.example",
    …
  },
  "group": null,
  "scope": "to_date",
  "share_through": "2026-09-14T17:05:22.318Z",
  "note": "Background on the Wildgrove renewal, up to today.",
  "created_at": "2026-09-14T17:05:22.318Z"
}
post/{record_type}/{record_id}/shares Write key

#Create a share

Shares a record visible to your key with users and groups in your account, as your key’s user. Carom creates one share per new recipient and notifies them.

You can’t set share_through when creating a share: a to_date share gets the current time as its cutoff. Use Update a share to change it.

Recipients who already have a share of this record from your key’s user are skipped, and shares contains only the new shares. If every recipient already has one, nothing changes, nobody is notified, and shares lists all of your key’s user’s shares of the record.

Path parameters

  • record_typestringrequired

    The plural resource name, one of:

    threadsfilescontactsorganizations
  • record_idstring · uuidrequired

    The id of that record. In the OpenAPI spec each route names it after its type, for example contact_id.

    Show 4 pathsHide paths
    • /threads/{thread_id}/shares
    • /files/{file_id}/shares
    • /contacts/{contact_id}/shares
    • /organizations/{organization_id}/shares

Request body application/json

  • shareobjectrequired

    Give at least one user or group.

    Show 4 child attributesHide child attributes
    • user_idsarray of strings · uuid

      Users in your account.

    • group_idsarray of strings · uuid

      Groups in your account.

    • scopestring

      See scope on the share object. Omit for a share with no cutoff.

      ongoingto_dateinteractions
    • notestring · nullable

      A message to the recipients.

Returns

  • sharesarray of shares

    The shares created, one per new recipient. When every recipient already had a share, all of your key’s user’s shares of the record.

Errors

  • 400no_recipientsBoth user_ids and group_ids are empty or missing.
  • 400invalid_share_scopescope isn’t one of the values above, or is interactions on a thread or file.
  • 400recipient_not_in_accountA user or group id doesn’t belong to your account.
  • 400invalid_requestThe share object is missing or malformed, or an entry in user_ids or group_ids isn’t a UUID.
  • 404record_not_foundNo record of that type with that id is visible to your key.
post/threads/{thread_id}/shares 
curl https://api.carom.io/threads/8b1c2d3e-4f5a-4b6c-9d7e-8f9a0b1c2d3e/shares \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "share": {
      "user_ids": ["4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84"],
      "scope": "to_date",
      "note": "Background on the Wildgrove renewal, up to today."
    }
  }'
Response200 
{
  "shares": [
    {
      "id": "f4e3d2c1-b0a9-4876-9543-210fedcba987",
      "sharer_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
      "user": {
        "id": "4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84",
        "first_name": "Jordan",
        …
      },
      "group": null,
      "scope": "to_date",
      "share_through": "2026-09-14T17:05:22.318Z",
      "note": "Background on the Wildgrove renewal, up to today.",
      "created_at": "2026-09-14T17:05:22.318Z"
    }
  ]
}
patch/{record_type}/{record_id}/shares/{id} Write key

#Update a share

Changes the note, scope, or cutoff of a share your key’s user made. When the result is a to_date share and you don’t send share_through, the share keeps its existing cutoff, or gets the current time if it has none.

Path parameters

  • record_type, record_idrequired

    The shared record, as on Create a share. It must be the record the share belongs to.

  • idstring · uuidrequired

    The share’s id.

Request body application/json

  • shareobjectrequired
    Show 3 child attributesHide child attributes
    • notestring · nullable
    • scopestring · nullable

      As on Create a share.

      ongoingto_dateinteractions
    • share_throughstring · date-time · nullable

      A new cutoff for a to_date share.

Returns

The updated share object, wrapped in share.

Errors

  • 400invalid_share_scopescope isn’t allowed for this record type.
  • 403permission_deniedYour key’s user can see the share but didn’t make it.
  • 404record_not_foundNo share with that id belongs to the record in the path, or your key’s user can see neither the share’s record nor the share as its sharer or recipient.
patch/threads/{thread_id}/shares/{id} 
curl -X PATCH https://api.carom.io/threads/8b1c2d3e-4f5a-4b6c-9d7e-8f9a0b1c2d3e/shares/f4e3d2c1-b0a9-4876-9543-210fedcba987 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "share": { "scope": "ongoing" } }'
Response200 
{
  "share": {
    "id": "f4e3d2c1-b0a9-4876-9543-210fedcba987",
    "sharer_id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "scope": "ongoing",
    "note": "Background on the Wildgrove renewal, up to today.",
    …
  }
}
delete/{record_type}/{record_id}/shares/{id} Write key

#Delete a share

Revokes a share your key’s user made. The recipient loses the access that share gave them; access they have through their own mailbox or another share is unaffected.

Path parameters

Returns

The ok object, {"ok": "ok"}.

Errors

  • 403permission_deniedYour key’s user can see the share but didn’t make it.
  • 404record_not_foundNo share with that id belongs to the record in the path, or your key’s user can see neither the share’s record nor the share as its sharer or recipient.
delete/threads/{thread_id}/shares/{id} 
curl -X DELETE https://api.carom.io/threads/8b1c2d3e-4f5a-4b6c-9d7e-8f9a0b1c2d3e/shares/f4e3d2c1-b0a9-4876-9543-210fedcba987 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{ "ok": "ok" }