Share requests

A share request asks colleagues whose mailboxes have corresponded with a contact to share that correspondence with you. Each colleague asked can accept, which creates an interactions share of the contact from them to you, or dismiss the request.

Share requests are private in both directions. As the requester, you see the users you named, but not who else was asked, whether anyone answered, or how. The only sign of an acceptance is the share it creates. As a recipient, you see the request, who sent it, and your own answer.

#The share request object

A request as its sender sees it. Returned by List share requests with role=requester, and by Create and Update a share request. Recipients see a different shape, described under List share requests.

Attributes

  • idstring · uuid

    Unique identifier for the request.

  • contactobject · nullable

    The contact the request is about.

    Show 3 child attributesHide child attributes
    • idstring · uuid
    • namestring · nullable
    • email_addressesarray of objects

      Each with an id, value, and primary, as on the contact object.

  • audiencestring

    Who was asked. everyone asks every user in the account whose mailbox has corresponded with one of the contact’s email addresses. selected asks the users you named, and others only if include_unknown is true.

    everyoneselected
  • include_unknownboolean

    On a selected request, whether it also asks colleagues who have corresponded with the contact but aren’t listed as knowing them. You aren’t told who they are.

  • named_recipientsarray of objects

    The users you named, in the order you asked them. Empty for an everyone request.

    Show 2 child attributesHide child attributes
    • user_idstring · uuid
    • requested_atstring · date-time

      When you asked this user.

  • notestring · nullable

    A message from the requester to the people asked.

  • created_atstring · date-time
The share request object 
{
  "id": "2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64",
  "contact": {
    "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
    "name": "Priya Natarajan",
    "email_addresses": [
      {
        "id": "3a8d1e6f-52c4-4b9a-8e7d-1c0f9b2a4d63",
        "value": "priya@wildgrove.example",
        "primary": true
      }
    ]
  },
  "audience": "selected",
  "include_unknown": false,
  "named_recipients": [
    {
      "user_id": "4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84",
      "requested_at": "2026-09-15T14:12:40.529Z"
    }
  ],
  "note": "I'm taking over the Wildgrove renewal. Could you share your history with Priya?",
  "created_at": "2026-09-15T14:12:40.529Z"
}
get/share_requests Read key

#List share requests

Returns every request sent to your key’s user in one response, newest first, including ones they have already answered; the list isn’t paginated. With role=requester, returns the requests they made instead, as share request objects.

Query parameters

  • rolestringdefault recipient

    recipient for requests sent to your key’s user; requester for requests they made.

    recipientrequester

Returns

With role=requester, share_requests is an array of share request objects. Otherwise it is an array of the entries below, one per request sent to you.

  • share_requestsarray of objects
    Show 4 child attributesHide child attributes
    • statestring

      Your answer so far.

      pendingaccepteddismissed
    • namedboolean

      True when the requester asked you by name.

    • responded_atstring · date-time · nullable
    • share_requestobject · nullable

      The request: id, which you pass to Respond to a share request, audience, include_unknown, note, created_at, and contact as on the share request object, plus the requester.

      Show 1 child attributeHide child attributes
      • requesterobject · nullable

        The user who sent the request: id, first_name, last_name, email_address, and avatar_color.

Errors

  • 400invalid_requestrole isn’t recipient or requester.
get/share_requests 
curl https://api.carom.io/share_requests \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response200 
{
  "share_requests": [
    {
      "state": "pending",
      "named": true,
      "responded_at": null,
      "share_request": {
        "id": "2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64",
        "audience": "selected",
        "include_unknown": false,
        "note": "I'm taking over the Wildgrove renewal. Could you share your history with Priya?",
        "created_at": "2026-09-15T14:12:40.529Z",
        "requester": {
          "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
          "first_name": "Dana",
          "last_name": "Whitfield",
          "email_address": "dana@harborline.example",
          "avatar_color": "#5b8def"
        },
        "contact": {
          "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
          "name": "Priya Natarajan",
          …
        }
      }
    }
  ]
}
post/contacts/{contact_id}/share_requests Write key

#Create a share request

Asks colleagues, on behalf of your key’s user, to share their correspondence with a contact visible to your key. Carom notifies each person asked.

For a selected request, each user in user_ids must be one Carom lists as knowing the contact, such as the users in known_by from Retrieve a contact. You can have one request per contact and audience. The response is the same whether Carom found anyone to ask or not.

Path parameters

  • contact_idstring · uuidrequired

    The contact’s id.

Request body application/json

  • share_requestobjectrequired
    Show 4 child attributesHide child attributes
    • audiencestringrequired

      See the share request object.

      everyoneselected
    • user_idsarray of strings · uuid

      The users to ask. selected only. Required unless include_unknown is true.

    • include_unknownboolean · nullabledefault false

      Also ask colleagues who have corresponded with the contact but aren’t listed as knowing them. selected only.

    • notestring · nullable

      A message to the people asked.

Returns

The new share request object, wrapped in share_request, with status 201.

Errors

  • 400invalid_requestaudience isn’t one of the values above; user_ids or include_unknown was sent with everyone; or a selected request names nobody and doesn’t set include_unknown.
  • 400ineligible_recipientsA user in user_ids isn’t listed as knowing the contact.
  • 404record_not_foundNo contact with that id is visible to your key.
  • 409duplicate_share_requestYour key’s user already has a request with this audience for this contact.
post/contacts/{contact_id}/share_requests 
curl https://api.carom.io/contacts/1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41/share_requests \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "share_request": {
      "audience": "selected",
      "user_ids": ["4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84"],
      "note": "I'm taking over the Wildgrove renewal. Could you share your history with Priya?"
    }
  }'
Response201 
{
  "share_request": {
    "id": "2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64",
    "contact": {
      "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
      "name": "Priya Natarajan",
      …
    },
    "audience": "selected",
    "include_unknown": false,
    "named_recipients": [
      {
        "user_id": "4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84",
        "requested_at": "2026-09-15T14:12:40.529Z"
      }
    ],
    "note": "I'm taking over the Wildgrove renewal. Could you share your history with Priya?",
    "created_at": "2026-09-15T14:12:40.529Z"
  }
}
patch/share_requests/{id} Write key

#Update a share request

Asks more people on a selected request your key’s user made. Name more users in user_ids, set include_unknown to true, or both. Only people not already asked are notified; a user who was already asked is marked as named, and their answer, if any, stands.

include_unknown can be turned on but not off; false is ignored. The response is the same whether or not anyone new was asked.

Path parameters

  • idstring · uuidrequired

    The request’s id.

Request body application/json

  • share_requestobjectrequired
    Show 2 child attributesHide child attributes
    • user_idsarray of strings · uuid

      Users to add. Each must be listed as knowing the contact, as on Create a share request.

    • include_unknownboolean · nullable

      true to also ask colleagues who have corresponded with the contact but aren’t listed as knowing them.

Returns

The share request object, wrapped in share_request.

Errors

  • 400invalid_requestThe request’s audience is everyone, or the body names nobody and doesn’t turn on include_unknown.
  • 400ineligible_recipientsA user in user_ids isn’t listed as knowing the contact.
  • 404record_not_foundYour key’s user has no request with that id, or has withdrawn it.
patch/share_requests/{id} 
curl -X PATCH https://api.carom.io/share_requests/2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64 \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "share_request": { "include_unknown": true } }'
Response200 
{
  "share_request": {
    "id": "2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64",
    "audience": "selected",
    "include_unknown": true,
    "named_recipients": [
      {
        "user_id": "4e7a2c1b-8d3f-4a6e-9b5c-7f1d0e2a3b84",
        "requested_at": "2026-09-15T14:12:40.529Z"
      }
    ],
    …
  }
}
delete/share_requests/{id} Write key

#Withdraw a share request

Withdraws a request your key’s user made. The request leaves their list and every recipient’s list, and can no longer be answered. Shares that recipients created by accepting it stay in place. Your key’s user can then make a new request for the same contact and audience.

Path parameters

  • idstring · uuidrequired

    The request’s id.

Returns

An empty response with status 204.

Errors

  • 404record_not_foundYour key’s user has no request with that id, or has already withdrawn it.
delete/share_requests/{id} 
curl -X DELETE https://api.carom.io/share_requests/2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64 \
  -H "Authorization: Bearer $CAROM_API_KEY"
Response204 
No content
post/share_requests/{id}/respond Write key

#Respond to a share request

Answers a request sent to your key’s user. accept creates an interactions share of the contact from your key’s user to the requester, and the requester is notified of the share. dismiss records the answer and notifies nobody. Each recipient can answer once.

Path parameters

Request body application/json

  • responsestringrequired
    acceptdismiss

Returns

An empty response with status 204.

Errors

  • 400invalid_requestresponse isn’t accept or dismiss.
  • 404record_not_foundNo request with that id was sent to your key’s user, or the requester withdrew it.
  • 409already_respondedYour key’s user has already answered this request.
post/share_requests/{id}/respond 
curl https://api.carom.io/share_requests/2c9e7b41-6a3d-4f8e-b5c2-9d1a0e7f3b64/respond \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "response": "accept" }'
Response204 
No content