Search

Search runs one text query against several kinds of record at once and returns a separate page of matches for each: files, threads, contacts, organizations, and deals. Use it for a search box, or to resolve a name someone typed into the record it refers to.

Each resource is searched with the same visibility rules as its own list endpoint, so results include only records visible to your key. Search is a POST so the query travels in the body, but it changes nothing and accepts a read key.

post/search Read key

#Search records

Matches query against each requested resource and returns up to limit records per resource, with a total for each. Resources you didn’t ask for come back as null.

Every resource is paged with the same page number. To see more contacts without re-fetching the others, request "resources": ["contacts"] with the next page.

Request body application/json

  • querystringrequired

    The text to search for. Must not be empty.

  • resourcesarray of strings

    Which resources to search. Omit, or send an empty array, to search all of them.

    filesthreadscontactsorganizationsdeals
  • limitintegerdefault 10

    Records per resource, between 1 and 50. Larger values are treated as 50. The limit applies to each resource separately.

  • pageintegerdefault 1

    Which page of each resource’s matches to return, counting from 1.

  • scopestring · nullable

    Passed to each resource’s own scope filter, as the scope parameter of that resource’s list endpoint would be, for example global or personal on contacts. Deals ignore it.

Returns

  • searchobject
    Show 3 child attributesHide child attributes
    • querystring

      The query, echoed back.

    • scopestring · nullable

      The scope, echoed back.

    • result_setobject

      One entry per resource. Each is null when that resource wasn’t searched, and otherwise has a total_results count of all matches and a page of records.

      Show 5 child attributesHide child attributes
      • filesobject · nullable

        Matching files, in a short form: id, name, file_name, extension, description, first_sent_at, last_sent_at, and participants, an object keyed by email address whose values are a contact in the short form below, a display name, or null. decorative attachments are always left out, as List files leaves them out by default.

      • contactsobject · nullable

        Matching contacts, in a short form: id, name, contact_type, global, user_id, background, and avatar. People rank ahead of mailing lists and notification senders.

      • threadsobject · nullable

        Matching thread objects, in full.

      • organizationsobject · nullable

        Matching organizations, in a short form: id, name, description, domain, and logo.

      • dealsobject · nullable

        Matching deals, newest first. Each carries its stage’s name as pipeline_stage_name, and its counterparty as a short-form contact or organization.

Errors

  • 400invalid_requestquery is missing or empty, or resources names something that can’t be searched.
post/search 
curl https://api.carom.io/search \
  -H "Authorization: Bearer $CAROM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "wildgrove",
    "resources": ["contacts", "organizations", "deals"],
    "limit": 5
  }'
Response200 
{
  "search": {
    "query": "wildgrove",
    "scope": null,
    "result_set": {
      "files": null,
      "contacts": {
        "total_results": 1,
        "records": [
          {
            "id": "1f3c9a52-7b0e-4d4a-9c1e-2a6f0d8b3e41",
            "global": true,
            "name": "Priya Natarajan",
            "background": "Runs operations across Wildgrove's 14 properties.",
            "user_id": null,
            "contact_type": "connection",
            "avatar": null
          }
        ]
      },
      "threads": null,
      "organizations": {
        "total_results": 1,
        "records": [
          {
            "id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
            "name": "Wildgrove Property Management",
            "description": "Residential property manager in the East Bay.",
            "domain": "wildgrove.example",
            "logo": null
          }
        ]
      },
      "deals": {
        "total_results": 1,
        "records": [
          {
            "id": "8f2b6d4a-1c9e-4a7b-b3d5-0e6f8a2c4d17",
            "name": "Wildgrove portfolio renewal",
            "status": "open",
            "amount": 48000.0,
            "currency": "USD",
            "pipeline_id": "5e8a1c3f-7b2d-4f6e-a9c0-3d1b7e4f2a86",
            "pipeline_stage_id": "4f6a8c0e-2b4d-4c6e-8f0a-3b5d7e9f1c28",
            "pipeline_stage_name": "Negotiation",
            "organization_id": "6b0e2d9a-4c31-4f8e-a7d2-90c4e1b7f5a3",
            "closed_at": null,
            …
          }
        ]
      }
    }
  }
}