# 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.

## 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 | 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. |

**`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`

---

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