# query contacts

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

Query contacts with filtering, sorting, and pagination using CRUD query language. Supports complex filters, sorting by multiple fields, and pagination.

## 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 |
| `ss` | query | string | no | Sort style: 'json' or 'simple' (default 'simple') |
| `s` | query | string | no | Sort expression in the format specified by ss param |

## Responses

### 200 — Paginated list of contacts

Content-Type: `application/json` · Schema: `crud.ListBaseResponse-orm_IdentityContact`

**`crud.ListBaseResponse-orm_IdentityContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array<orm.IdentityContact> | no |  |
| `page_number` | integer | no |  |
| `page_size` | integer | no |  |
| `total_count` | integer | no |  |

**`orm.IdentityContact`** 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 (PE-9161). 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`

---

Interactive API reference: https://doc.suger.io/api/