# List known partner contacts for a buyer company

`GET https://api.suger.cloud/org/{orgId}/cosell/partner_contact`

Look up partner-side contacts (AWS / AZURE / GCP partner reps) associated with a buyer company, identified by its primary email domain (e.g. "acme.com"). Each contact comes back with a per-partner count of historical referrals, so the caller can identify counterparts by referral volume.

Use this when: user is drafting a co-sell referral and needs to pick which partner contact to assign, or wants to see "who at AWS / Azure / GCP have we worked with for this company before".

Here "partner" means the cloud provider, and the domain you pass is the CUSTOMER's. For the people at a company in your own partner program, use GetPrmPartnerContacts, which takes a partnership id. Standing Partner Development Managers are left out of these results, since they are not tied to a particular deal.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `companyDomain` | query | string | yes | Domain of the buyer company to look up |

## Responses

### 200 — Partner contacts response

Content-Type: `application/json` · Schema: `PartnerContactsResponse`

**`PartnerContactsResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `companyDomain` | string | no | The buyer company domain used for the query |
| `contacts` | array<PartnerContactInfo> | no | Partner contacts with their referral counts per partner |

**`PartnerContactInfo`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contact` | IdentityContact | no |  |
| `partnerCounts` | object | no | Referral counts per partner (e.g., {"AWS": 3, "AZURE": 1}) |

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

### 400 — Bad request error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

### 500 — Internal server error

Content-Type: `application/json` · Schema: `ErrorResponse`

**`ErrorResponse`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | ErrorCode | no |  |
| `info` | object | no |  |
| `message` | string | no |  |

---

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