list contacts

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

List all contacts under the given organization. If contactIds parameter is provided, return only those specific contacts. Results come back in no particular order and this operation takes no sort parameter, so it cannot answer "top N by..." questions; QueryContacts covers ordering, numeric comparisons, and the co-sell metric fields such as open pipeline.

Parameters

Name	In	Type	Required	Description
`orgId`	path	string	yes	Organization ID
`contactIds`	query	string	no	Comma-separated list of contact IDs to fetch specific contacts, up to 100 IDs
`emailDomain`	query	string	no	Email domain to filter contacts
`keyword`	query	string	no	keyword to search contacts by name or email
`limit`	query	integer	no	List pagination size, default 1000, max value is 1000 (ignored when contactIds is provided)
`offset`	query	integer	no	List pagination offset, default 0 (ignored when contactIds is provided)

Responses

200 — OK

Content-Type: application/json

IdentityContact fields:

Field	Type	Required	Description
`companyContactId`	string	no
`creationTime`	string	no
`emailAddress`	string	no
`id`	string	no	This is generated by Suger. When you create a new contact, do not provide.
`info`	IdentityConctactInfo	no
`lastUpdateTime`	string	no
`name`	string	no
`organizationID`	string	no
`tags`	array<string>	no

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

WorkExperience fields:

Field	Type	Required	Description
`current`	boolean	no	true if the work experience is current
`endDate`	string	no
`organizationName`	string	no
`startDate`	string	no
`title`	string	no

400 — Bad request error description

Content-Type: application/json

500 — internal error description

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.