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
`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
`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).
`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

View as Markdown · Interactive API reference

Spotted something wrong or out of date on this page? Tell us and we'll correct it.