Contacts

Attributes

• idstring · uuid

  Unique identifier for the contact.

• namestring · nullable

  Display name. Null when Carom has only ever seen an email address for this person.

• contact_typestring

  What kind of sender the contact is. Carom classifies each contact automatically; you can override it. connection: a person outside your organization. colleague: a person at your organization, with an address at your account’s email domain. mailing_list: a mailing list or newsletter. notification: an automated sender, such as a no-reply address.

  connectioncolleaguemailing_listnotification
• globalboolean

  True for a global contact, visible to the whole account; false for a personal one. Change it with Make a contact global.

• backgroundstring · nullable

  Free-form notes about the person.

• pinnedboolean · nullable

  Whether your key’s user has pinned this contact. Null on contacts embedded in other resources’ responses.

• has_duplicatesboolean · nullable

  True when Carom has found other contacts that look like the same person and nobody has rejected the match. See List duplicates, and resolve them with Merge contacts. Null on contacts embedded in other resources’ responses.

• user_idstring · uuid · nullable

  The user who owns the contact. Only the owner can make it global.

• task_countinteger · nullable

  Open tasks attached to this contact that are visible to your key. Null on contacts embedded in other resources’ responses.

• prioritynumber

  List responses only. A relative score of how actively your team corresponds with this contact. Higher is more active; it has no fixed scale, so use it to sort. The default sort for List contacts.

• thread_countinteger

  List responses only. Threads with this contact, summed across the mailboxes whose statistics are visible to your key.

• file_countinteger

  List responses only. Files attached to messages with this contact, summed the same way.

• last_contactstring · date-time · nullable

  List responses only. When a thread with this contact last had a message, in those mailboxes.

• recent_monthly_messagesobject

  List responses only. Messages with this contact per month for the trailing 12 months, keyed by month as YYYY-MM, oldest first.

• email_addressesarray of objects · nullable

  Every address Carom has seen for this person.

  Show 3 child attributesHide child attributes

  • idstring · uuid
  • valuestring · nullable

    The address.

  • primaryboolean · nullable

    Addresses added through the API are primary; addresses moved onto this contact by a merge are not. A contact can have more than one primary address.

• employmentsarray of objects · nullable

  Roles this person holds, each at an organization.

  Show 3 child attributesHide child attributes

  • idstring · uuid
  • titlestring · nullable

    Job title.

  • organizationobject · nullable
    Show 2 child attributesHide child attributes

    • idstring · uuid
    • namestring · nullable
• numbersarray of objects · nullable

  Phone numbers, each with a free-form kind.

  Show 3 child attributesHide child attributes

  • idstring · uuid
  • valuestring · nullable
  • kindstring · nullable
• locationsarray of objects · nullable

  Postal addresses, with a time zone when one is known.

  Show 11 child attributesHide child attributes

  • idstring · uuid
  • street_numberstring · nullable
  • streetstring · nullable
  • apartmentstring · nullable
  • citystring · nullable
  • statestring · nullable
  • state_codestring · nullable
  • countrystring · nullable
  • country_codestring · nullable
  • time_zonestring · nullable

    Time zone name.

  • utc_offsetnumber · nullable

    Offset from UTC, in hours.

• social_profilesarray of objects · nullable

  Profiles on linkedin, twitter, github, facebook, or angellist, each with an id, network, and handle.

• websitesarray of objects · nullable

  Links associated with the person, each with an id, url, and title.

• avatarobject · nullable

  The contact’s picture: an id, a source_url you can display directly, and a file_name.

• tagsarray of tags · nullable

  Tags applied to this contact.

• interaction_historiesarray of objects · nullable

  Single-contact responses only. One entry for each pair of email address and mailbox whose statistics are visible to your key, describing that mailbox’s correspondence with this contact.

  Show 12 child attributesHide child attributes

  • mailbox_idstring · uuid
  • mailboxobject · nullable

    Identifies the mailbox. An entry can be visible to your key when the mailbox itself isn’t, so this carries only the fields below; read the rest from Mailboxes.

    Show 4 child attributesHide child attributes

    • idstring · uuid
    • email_addressstring · nullable
    • namestring · nullable

      Display name for the mailbox.

    • user_idstring · uuid · nullable

      The user who owns the mailbox.

  • thread_countinteger · nullable
  • file_countinteger · nullable
  • response_ratenumber · nullable

    Share of threads with this contact in which the mailbox sent a message, between 0 and 1.

  • prioritynumber · nullable

    A relative score of how actively this mailbox corresponds with the contact. Higher is more active; it has no fixed scale, so use it to sort.

  • average_thread_laginteger · nullable

    Average time between messages in threads with this contact, in seconds.

  • average_thread_lengthnumber · nullable

    Average messages per thread.

  • average_participant_countnumber · nullable

    Average participants per thread.

  • monthly_messagesobject · nullable

    Message counts keyed by month, as YYYY-MM, from the first month with a message.

  • first_contactstring · date-time · nullable
  • last_contactstring · date-time · nullable
• tasksarray of tasks · nullable

  Single-contact responses only. Open tasks attached to the contact that your key can see.

• commentsarray of comments · nullable

  Single-contact responses only. Comments your team has left on the contact.

• sharesarray of shares · nullable

  Single-contact responses only. Active shares of this contact with users or groups.

Query parameters

• querystring

  Match part of the contact’s name, background, or any of its email addresses. Up to 500 characters.

• scopestring

  Restrict to global or personal contacts. Omit, or send any other value, to include both.

  globalpersonal
• slicestring

  A preset filter. automated: mailing lists and notifications instead of people. latest: last contact within the past 30 days in at least one mailbox. lapsed: last contact more than 90 days ago in at least one mailbox. shared: contacts shared with your key’s user or their groups. tasked: contacts with an open task owned by your key’s user. pinned: contacts your key’s user has pinned. duplicated: contacts with possible duplicates.

  automatedlatestlapsedsharedtaskedpinnedduplicated
• sortstringdefault priority

  Field to sort by. Any other value sorts by priority.

  prioritylast_contactthread_countname
• orderstring

  Defaults to desc for priority, last_contact, and thread_count, and to asc for name. Any other value uses the default.

  ascdesc
• tagsstring

  Comma-separated tag ids, at most 50.

• tag_operatorstringdefault any

  Whether a contact 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 contacts and the cursor to the next one.

  Show 3 child attributesHide child attributes

  • recordsarray of contacts

    Up to 50 contacts in the requested order, with the list-only statistics and without the single-contact embeds.

  • 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, scope, 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 more than 50 tag ids or a query over 500 characters.
• 400invalid_cursorThe cursor is unreadable, or came from another list or sort.
• 400unsupported_cursor_directionA prev_cursor was sent. This list pages forward only.

Request body application/json

• contactobjectrequired
  Show 10 child attributesHide child attributes

  • namestring

    Required unless you supply at least one email address.

  • email_addressesarray of objects

    Each with a value. Carom stores addresses in lowercase.

  • contact_typestring

    Omit to have Carom classify the contact from its first email address. Without an email address, the contact is a connection.

    connectioncolleaguemailing_listnotification
  • backgroundstring

    Free-form notes about the person.

  • employmentsarray of objects

    A title and an organization. Link an existing organization by its id, or give a name without an id to create a new organization.

    Show 2 child attributesHide child attributes

    • titlestring
    • organizationobject
      Show 2 child attributesHide child attributes

      • idstring · uuid

        Id of an existing organization in your account, to link it. Other fields sent with id are ignored; to change the organization, use Update an organization.

      • namestring

        Name for a new organization. Required when id is omitted.

  • numbersarray of objects

    Each with a value (required) and an optional kind.

  • social_profilesarray of objects

    Each with a network and handle.

    linkedintwittergithubfacebookangellist
  • locationsarray of objects

    Each with any of street_number, street, apartment, city, state, and country_code.

  • websitesarray of objects

    Each with a url (required).

  • avatar_upload_idstring · uuid

    Id of an image you uploaded to use as the picture. On update, send null to remove the picture.

Returns

Errors

• 400missing_name_or_emailNeither a name nor an email address was given.
• 400missing_emailcontact_type was omitted and the first email address is blank.
• 400duplicate_association_recordAn email address is already on another contact owned by your key’s user.
• 400invalid_requestA field failed validation. error.fields says which. An organization id that isn’t a UUID or doesn’t name an organization in your account is reported on its employment’s index, such as employments.0.organization.id; an organization with neither id nor name, on employments.0.organization.name.

Path parameters

• idstring · uuidrequired

  The contact’s id.

Returns

• countsobject
  Show 2 child attributesHide child attributes

  • open_tasksinteger

    All open tasks attached to the contact that are visible to your key.

  • upcoming_eventsinteger

    Calendar events with the contact from today on.

• eventsarray of calendar events

  Up to three upcoming calendar events with the contact.

• timelineobject · nullable

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

• known_byarray of strings · uuid

  Ids of other users whose mailboxes have corresponded with this contact and share that knowledge with the account (interaction_sharing is knowledge), but whose statistics aren’t visible to your key. Ask them for access with a share request. Empty when there are none.

Errors

• 404record_not_foundNo contact with that id is visible to your key.

Path parameters

• idstring · uuidrequired

Request body application/json

• contactobjectrequired

  Any of the attributes accepted by Create a contact. Entries in nested collections take two more fields.

  Show 2 child attributesHide child attributes

  • idstring · uuid

    On a nested entry: the entry to change. Omit to add one.

  • deletedboolean

    On a nested entry: remove it.

Returns

Errors

• 400missing_name_or_emailThe request sends name or email_addresses, but neither has a value.
• 400duplicate_association_recordAn email address is already on another contact owned by your key’s user.
• 400invalid_requestA field failed validation, as on Create a contact, or a nested entry’s id isn’t a UUID. error.fields says which.
• 403permission_deniedThe contact is visible to your key but not editable by it, for example a personal contact another user shared with your key’s user.
• 404record_not_foundNo contact with that id is visible to your key.

Path parameters

• idstring · uuidrequired

Returns

Errors

• 403permission_deniedThe contact is visible to your key but your key’s user can’t delete it: a personal contact they don’t own, or a global contact when they aren’t an account admin.
• 404record_not_foundNo contact with that id is visible to your key.
• 409contact_has_dealsThe contact is the counterparty of at least one deal. Nothing was deleted.

Query parameters

• query, scope, slice, tags, tag_operator

  As on List contacts.

• capinteger

  Stop counting at this many. When more contacts 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

    True when counting stopped at cap.

  • capinteger · nullable

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

Errors

• 400invalid_requestA parameter is malformed, as on List contacts.

Path parameters

• idstring · uuidrequired

Request body application/json

• globalbooleanrequired

  true to make the contact global. false is accepted only for a contact that is already personal, and changes nothing.

Returns

Errors

• 400cannot_unglobalizeglobal is false and the contact is already global.
• 403permission_deniedYour key’s user doesn’t own the contact.
• 404record_not_foundNo contact with that id is visible to your key.

Path parameters

• idstring · uuidrequired

  The contact to keep.

Request body application/json

• contact_idsarray of strings · uuidrequired

  The contacts to merge into the target, at most 10. Don’t include the target itself.

Returns

Errors

• 400missing_source_contactscontact_ids is empty.
• 400invalid_requestcontact_ids is missing, isn’t an array of UUIDs, or holds more than 10 ids.
• 403contacts_not_editableYour key’s user can’t edit one of the contacts involved.
• 404record_not_foundThe target or one of the contact_ids isn’t a contact visible to your key.
• 409target_in_sourcescontact_ids includes the target contact.

Path parameters

• idstring · uuidrequired

Returns

• discussionobject
  Show 1 child attributeHide child attributes

  • scopesarray of objects · nullable

    The contact’s own scope first, then its deals.

    Show 6 child attributesHide child attributes

    • keystring · nullable
      contactdeals
    • labelstring · nullable

      A display name for the scope, such as This contact.

    • unitstring · nullable

      The plural noun for the scope’s records, such as deals.

    • primaryboolean · nullable

      True for the contact’s own scope.

    • total_commentsinteger · nullable
    • recordsarray of objects · nullable

      The records in the scope that have comments, most recently discussed first. The contact’s own scope always holds the contact, even with no comments.

      Show 6 child attributesHide child attributes

      • keystring · nullable

        record_type and record_id joined with a hyphen.

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

        Oldest first.

Errors

• 404record_not_foundNo contact with that id is visible to your key.