# Query Contacts

`GET https://api.suger.cloud/org/{orgId}/contact/query`

Query contacts with filtering, sorting, and pagination using the CRUD query language. Use it to rank or narrow contacts by a stored value, such as the top 10 AWS sales reps by open pipeline. Filtering and sorting are applied across the whole result set before pagination, so page 1 holds the global top N. Filters go in q, with qs=json selecting a tree of {"operator","field","value"} nodes combined by and/or; operators include =, !=, >, >=, <, <=, between, in, like, ilike, contains, exists and is_null. Sorts go in s, with ss=json selecting [{"field":"...","direction":"DESC","type":"numeric","nullsLast":true}]. Set type=numeric when ordering by a number, so 1000000 orders above 72000, and nullsLast=true so contacts with no value for that field collect at the end in both directions. Set type=numeric only on a field that holds numbers: a numeric sort over text values is rejected with an invalid-input-syntax error, so order text fields with the default type=text. Cloud partner reps carry co-sell metrics under info.cosellPartnerMetrics: accountCount, inboundReferralCount, outboundReferralCount, closedWonCount, closedLostCount, successRate (win rate from 0 to 100), lastActiveTime, managedDomains, industries, plus pipeline and closedWonAmount. Those last two are objects keyed by currency, so address one currency per query, as in info.cosellPartnerMetrics.USD; a contact whose pipeline is held in another currency will not match. A cloud partner rep is identified by the tags array, which carries "partner" together with one of "aws", "azure" or "gcp". The console's Cloud Contacts view narrows further to reps holding a cloud-provider email address, so include that clause to reproduce the same set of rows it shows. Worked example for the top 10 AWS reps by open pipeline: qs=json, q={"operator":"and","args":[{"operator":"contains","field":"tags","value":"partner"},{"operator":"contains","field":"tags","value":"aws"},{"operator":"ilike","field":"email_address","value":"@amazon."}]}, ss=json, s=[{"field":"info.cosellPartnerMetrics.USD","direction":"DESC","type":"numeric","nullsLast":true}], page_size=10. ListContacts looks contacts up by keyword, email domain, or explicit IDs and returns them without ordering; ordering and the metric fields described above are available on this operation.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `page_size` | query | integer | no | Number of items per page (default 20, max 1000) |
| `page_number` | query | integer | no | Page number (default 1) |
| `qs` | query | string | no | Query style: 'json' or 'lisp' (default 'lisp') |
| `q` | query | string | no | Filter expression in the format specified by qs param. Numeric comparisons (>, >=, <, <=, between) on a numeric field are compared as numbers whether the value is sent as a JSON number or as a string. |
| `ss` | query | string | no | Sort style: 'json' or 'simple' (default 'simple'). Use 'json' to set type=numeric and nullsLast, which the 'simple' style cannot express. |
| `s` | query | string | no | Sort expression in the format specified by ss param. With ss=json this is a list of objects carrying field, direction (ASC or DESC), type (numeric, timestamp or text) and nullsLast; see this operation's description for a worked example. |

## Responses

### 200 — Paginated list of contacts

Content-Type: `application/json` · Schema: `ListBaseResponse-IdentityContact`

**`ListBaseResponse-IdentityContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<IdentityContactRow> | no |  |
| `page_number` | integer | no |  |
| `page_size` | integer | no |  |
| `total_count` | integer | no | TotalCount is the number of matching rows, counted up to ListCountCap. When TotalCountCapped is true it is that cap rather than the real total. |
| `total_count_capped` | boolean | no | TotalCountCapped reports that more rows match than TotalCount says: the count stopped at ListCountCap because an exact total costs a full scan of everything the filter matches. Clients should present TotalCount as a lower bound ("10,000+") when this is set. Omitted when false, so clients that predate the field are unaffected. |

**`IdentityContactRow`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companyContactId` | string | no | CompanyContactID holds the value of the "company_contact_id" field. |
| `creationTime` | string | no | CreationTime holds the value of the "creation_time" field. |
| `emailAddress` | string | no | EmailAddress holds the value of the "email_address" field. |
| `id` | string | no | ID of the ent. |
| `info` | IdentityConctactInfo | no |  |
| `lastUpdateTime` | string | no | LastUpdateTime holds the value of the "last_update_time" field. |
| `name` | string | no | Name holds the value of the "name" field. |
| `organizationID` | string | no | OrganizationID holds the value of the "organization_id" field. |
| `tags` | array<string> | no | Tags holds the value of the "tags" field. |

**`IdentityConctactInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companyLocation` | string | no |  |
| `companyName` | string | no |  |
| `cosellPartnerMetrics` | CosellPartnerContactMetrics | no |  |
| `enrichedContactInfo` | CompanyContact | no |  |
| `lastModifiedBy` | string | no |  |
| `partner` | Partner | no |  |
| `phoneNumber` | string | no |  |
| `role` | string | no |  |

**`CosellPartnerContactMetrics`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accountCount` | integer | no | AccountCount is the number of unique Salesforce accounts associated with this contact. This is len(Accounts) stored for efficient sorting/filtering. |
| `accounts` | array<AccountInfo> | no | Accounts contains Salesforce accounts associated with this contact's referrals. Account IDs are extracted from referrals, names are fetched from Salesforce. |
| `closedLostCount` | integer | no | ClosedLostCount is the number of referrals with status CLOSED_LOST where this contact is assigned. |
| `closedWonAmount` | object | no | ClosedWonAmount is the sum of deal values for CLOSED_WON referrals, grouped by currency. Format: {"USD": 500000.00, "EUR": 100000.00} |
| `closedWonCount` | integer | no | ClosedWonCount is the number of referrals with status CLOSED_WON where this contact is assigned. |
| `engagementTimeSeries` | array<MonthlyEngagement> | no | EngagementTimeSeries contains monthly engagement metrics for the last 6 months. Pre-computed during the daily cron workflow for efficient API responses. Sorted chronologically by period (oldest to newest). |
| `inboundReferralCount` | integer | no | InboundReferralCount is the number of inbound referrals (direction = INBOUND) where this contact is assigned. |
| `industries` | array<string> | no | Industries contains unique standardized industry classifications for this contact. Values are normalized to AWS ACE industry picklist (28 values). Priority: CRM account industry > referral industry (AWS/GCP only). |
| `lastActiveTime` | string | no | LastActiveTime is the most recent time this contact engaged in a co-sell referral: MAX(COALESCE(referral.external_creation_time, referral.creation_time)) across all of the contact's synced referrals, regardless of status. This is the contact-level roll-up of AccountInfo.LastReferralTime and drives the "Last Active" column on the Cloud Contacts table. nil for contacts with no synced referrals (e.g. Predicted contacts, which have no local referral activity). |
| `locations` | array<LocationWithRegion> | no | Locations contains customer locations with their mapped sales regions. Extracted from referral customer addresses and mapped to sales territories. |
| `managedDomains` | array<string> | no | ManagedDomains contains the unique customer domains from referrals where this partner contact is assigned. Extracted from buyer company domains. |
| `oppOwners` | array<OppOwner> | no | OppOwners contains unique opportunity owners from the contact's associated accounts. Aggregated from opportunities across all accounts for quick display. Deduplicated by email and sorted by name. |
| `outboundReferralCount` | integer | no | OutboundReferralCount is the number of outbound referrals (direction = OUTBOUND) where this contact is assigned. |
| `pipeline` | object | no | Pipeline is the sum of deal values for active (accepted) referrals, grouped by currency. Format: {"USD": 150000.00, "CAD": 25000.00} Includes only referrals that have been accepted by the partner. |
| `predictionMetrics` | CosellPartnerContactMetrics | no |  |
| `source` | string | no | Source indicates how this partner contact was created and its lifecycle state. "Referral": Contact with actual referral activity (created directly or transitioned from Predicted). "Predicted": Contact suggested based on domain matching from another organization. Lifecycle: Predicted → Referral (when contact gets referral activity). |
| `successRate` | number | no | SuccessRate is the win rate: (ClosedWonCount / [ClosedWonCount + ClosedLostCount]) × 100 nil if no closed referrals (ClosedWonCount + ClosedLostCount == 0) Note: Rejected/Declined/Expired referrals are NOT included (they were never active) |

**`CompanyContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `city` | string | no |  |
| `companyDomain` | string | no |  |
| `companyName` | string | no | Company information |
| `country` | string | no | Location information |
| `creationTime` | string | no | Timestamps |
| `email` | string | no | Contact information |
| `firstName` | string | no |  |
| `id` | string | no | Core identification fields |
| `info` | CompanyContactInfo | no |  |
| `jobFunction` | string | no |  |
| `jobTitle` | string | no | Professional information |
| `lastName` | string | no |  |
| `lastUpdateTime` | string | no |  |
| `linkedIn` | string | no |  |
| `name` | string | no |  |
| `phone` | string | no |  |
| `s3KeyPicture` | string | no | Media and social |
| `status` | EnrichmentDataStatus | no |  |
| `twitter` | string | no |  |

**`AccountInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createdDate` | string | no | CreatedDate is the account creation date in Salesforce (YYYY-MM-DD format). |
| `domain` | string | no | Domain is the account's domain extracted from the Website field in Salesforce. |
| `id` | string | no | ID is the Salesforce account ID. |
| `industry` | string | no | Industry is the account's industry classification from Salesforce. |
| `lastReferralTime` | string | no | LastReferralTime is the timestamp of the most recent referral this contact participated in for this account. Value is COALESCE(referral.external_creation_time, referral.creation_time) — "when the referral was shared with the partner platform". Populated daily by the partner_contact_metrics Temporal workflow and drives the SFDC Account Mapping freshness badge. For Predicted accounts this value is inherited from the source org's contact (via domain matching + CRM privacy filter). |
| `name` | string | no | Name is the account name (fetched from Salesforce). |
| `opportunities` | array<OpportunityInfo> | no | Opportunities contains the Salesforce opportunities for this account. Fetched via SOQL relationship query during cron workflow. |
| `partnerContactCollaborationScore` | PartnerContactCollaborationScore | no |  |
| `source` | string | no | Source indicates how this account was added to the partner contact. "Predicted": Added through domain matching in predicted contacts workflow. "Referral": Added through actual referral activity, or transitioned from Predicted. "Upload": Added by an admin CSV upload. Precedence (never downgrade): Predicted < Upload < Referral. Lifecycle: Predicted → Upload (CSV upload) / → Referral (referral activity). Uses PartnerContactSource* constants. |
| `type` | string | no | Type is the account type from Salesforce (e.g., "Customer", "Prospect", "Target"). |
| `uploadedAt` | string | no | UploadedAt is when this upload mapping was created or last re-uploaded. Set only when Source == PartnerContactSourceUpload. |
| `uploadedBy` | string | no | UploadedBy is the user ID that created or last refreshed this account mapping via CSV upload. Set only when Source == PartnerContactSourceUpload. |

**`MonthlyEngagement`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cosellDeals` | integer | no | CosellDeals is the number of referrals created in this month. |
| `opportunityActivity` | integer | no | OpportunityActivity is the number of opportunities with activity in this month. |
| `period` | string | no | Period is the month in YYYY-MM format (e.g., "2024-01"). |

**`LocationWithRegion`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `location` | string | no | Location is the customer location string (e.g., "Seattle, WA, US", "London, UK"). |
| `region` | string | no | Region is the mapped sales territory (e.g., "US West", "EMEA", "APAC"). |

**`OppOwner`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | no | Email is the opportunity owner's email address. |
| `name` | string | no | Name is the opportunity owner's name. |

**`CompanyContactInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apolloId` | string | no | ApolloID is the Apollo.io person ID for re-enrichment. |
| `isPrimary` | boolean | no | IsPrimary indicates this is the highest-seniority partnership contact. |
| `seniority` | string | no | Seniority is the contact's seniority level inferred from job title (e.g., "vp", "director", "manager", "ic"). |
| `workExperiences` | array<WorkExperience> | no |  |

**`OpportunityInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | no | Amount is the opportunity deal value. |
| `closeDate` | string | no | CloseDate is the expected or actual close date (YYYY-MM-DD format). |
| `createdDate` | string | no | CreatedDate is the opportunity creation date in Salesforce (YYYY-MM-DDTHH:MM:SS.000+0000 format). |
| `currencyIsoCode` | string | no | CurrencyIsoCode is the ISO currency code (e.g., "USD", "EUR"). |
| `id` | string | no | ID is the Salesforce opportunity ID. |
| `name` | string | no | Name is the opportunity name. |
| `ownerEmail` | string | no | OwnerEmail is the email of the opportunity owner (from Salesforce User). |
| `ownerName` | string | no | OwnerName is the name of the opportunity owner (from Salesforce User). |
| `probability` | number | no | Probability is the likelihood of closing the deal (0-100 percentage). |
| `stageName` | string | no | StageName is the current sales stage (e.g., "Prospecting", "Closed Won", "Closed Lost"). |

**`PartnerContactCollaborationScore`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `aiDeltaScore` | number | no | AIDeltaScore is the AI calibration delta in the range [-25, +25]. |
| `aiRationale` | string | no | AIRationale is a one-line holistic explanation produced by Layer 2. It is the single string the UI surfaces to explain the score. |
| `baseScore` | number | no | BaseScore is the rule-based component computed nightly: 0.30·reviewLayer + 0.70·referralBase, clamped to 0..100. |
| `finalScore` | number | no | FinalScore = clamp(BaseScore + AIDeltaScore, 0, 100). This is the value surfaced to read consumers. |
| `lastUpdateTime` | string | no | LastUpdateTime is when this struct was last (re)written by Layer 2. |

### 400 — Bad request error

Content-Type: `application/json`

### 500 — Internal server error

Content-Type: `application/json`

## Example

_Generated from this operation's schema. Values are placeholders — substitute your own ids, and set `SUGER_TOKEN` to a bearer token from the [OAuth client-credentials exchange](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X GET 'https://api.suger.cloud/org/{orgId}/contact/query' \
  -H "Authorization: Bearer $SUGER_TOKEN"
```

### Response — 200

```json
{
  "data": [
    {
      "companyContactId": "01H0000000000000000000",
      "creationTime": "2026-01-31T12:00:00Z",
      "emailAddress": "buyer@example.com",
      "id": "01H0000000000000000000",
      "info": {
        "companyLocation": "string",
        "companyName": "Acme Corp",
        "cosellPartnerMetrics": {
          "accountCount": 1,
          "accounts": [],
          "closedLostCount": 1,
          "closedWonAmount": {},
          "closedWonCount": 1,
          "engagementTimeSeries": [],
          "inboundReferralCount": 1,
          "industries": [],
          "lastActiveTime": "2026-01-31T12:00:00Z",
          "locations": [],
          "managedDomains": [],
          "oppOwners": []
        },
        "enrichedContactInfo": {
          "city": "string",
          "companyDomain": "string",
          "companyName": "Acme Corp",
          "country": "string",
          "creationTime": "2026-01-31T12:00:00Z",
          "email": "buyer@example.com",
          "firstName": "Acme Corp",
          "id": "01H0000000000000000000",
          "info": {},
          "jobFunction": "string",
          "jobTitle": "string",
          "lastName": "Acme Corp"
        },
        "lastModifiedBy": "string",
        "partner": "",
        "phoneNumber": "string",
        "role": "string"
      },
      "lastUpdateTime": "2026-01-31T12:00:00Z",
      "name": "Acme Corp",
      "organizationID": "01H0000000000000000000",
      "tags": [
        "string"
      ]
    }
  ],
  "page_number": 1,
  "page_size": 1,
  "total_count": 1,
  "total_count_capped": true
}
```

### Error — 400

```json
"string"
```

---

API reference: https://doc.fours.com/api/