# List Partner Contacts

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

The one list of the people at this organization's partners: the contacts Fours stores (added in the hub, from deal registrations, the partners' portal users and open portal invitations) and, for one partnership with `include` crm, its linked CRM Account's contacts. Needs partners.read; a partner organization lists its own partnerships only, never the seller's CRM.

By default (`view` group) the people come grouped by partner, A to Z, paged by group (1 to 100 groups a page). With `view` row they are one row per person per partnership, paged by row (1 to 200 a page), sorted by `sort` name or lastUpdate (the default, newest first) and `dir`, and the All tab's `filter` applies. With `view` row and `portalAccess` true the rows are the partners' portal users instead (members of their partner workspaces, and people invited to them); add `include` activity for each one's last sign-in, last action, deal registrations in the last 90 days, courses completed and certificates, which the activity sorts (lastSignIn, lastAction, deals90, courses, certificates), the `lastAction` filter and the ACTIVE_30D and INACTIVE_90D quick views need. NEVER_SIGNED_IN (open invitations) needs no activity.

Filter with `q`, `partnershipIds` (the partnership ids from ListPrmPartnerships), `role`, `source`, `syncStatus` and `mine` (partnerships whose Partner Manager is the signed-in user). People on your own email domain are left out and counted unless `includeOwnDomain` is true. With a search or a role, source or syncStatus filter, only partners with a match are grouped (and those named in `keep`).

With `include` crm and exactly one `partnershipIds` value that partnership is read as its partner page reads it, alone (the totals and facets are that partnership's), with one live read of its linked CRM Account: the Account's people come back with their CRM record id (`crmContactId`) and their real sync state, and `crmRead` says how the read went (OK, FAILED with the reason, or NOT_LINKED). People on the Account with no email address are listed only to a caller holding crm.read_record; for anyone else they are left out and counted in `crmRead.contactsWithheld`. A SUGGESTED partnership (one discovery suggested) is listed this way too. `include` crm with no or several `partnershipIds`, or with `portalAccess`, is refused (400). Any other list, one `partnershipIds` value without `include` crm included, reads no CRM: a row's syncStatus is its stored FAILED or PENDING, else UNCHECKED (the partner has a linked Account) or UNLINKED. `sort` name lists a group's people named first, then by name. An unknown partnership is an empty page.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `view` | query | string | no | group (the default) or row |
| `q` | query | string | no | Search name, email, title, role and partner name |
| `partnershipIds` | query | string | no | Partnership ids, comma separated (or the parameter repeated); one id reads its CRM Account live |
| `role` | query | string | no | Contacts only: PARTNER_MANAGER, EXECUTIVE, SALES, TECHNICAL, MARKETING, FINANCE_OPS or OTHER |
| `source` | query | string | no | Contacts only: CRM, PORTAL_USER, DEAL_REG or MANUAL |
| `syncStatus` | query | string | no | Contacts only: NOT_SYNCED, PENDING, SYNCED, FAILED, UNCHECKED or UNLINKED |
| `mine` | query | boolean | no | Only partnerships whose Partner Manager is the signed-in user |
| `includeOwnDomain` | query | boolean | no | Contacts only: also list people on your own email domain, flagged ownDomain |
| `keep` | query | string | no | Grouped view: partnership ids listed even when no person matches, comma separated |
| `sort` | query | string | no | Grouped view: name (named people first, then by name), or the partner page's order (the default). Row view: name or lastUpdate (the default); portal users: name or partner, and with the activity lastSignIn (the default), lastAction, deals90, courses or certificates |
| `dir` | query | string | no | Row view: asc or desc |
| `filter` | query | string | no | Row view, contacts: the All tab's filter as JSON (a QueryContacts condition) on name, emailAddress, info.companyName, info.phoneNumber or info.role, with the string operators |
| `portalAccess` | query | boolean | no | Row view: true lists the partners' portal users (workspace members and open portal invitations) |
| `include` | query | string | no | crm: with exactly one partnershipIds value, read that partnership's linked CRM Account live (not for portal users). Portal users: activity adds each one's activity, and allows the activity sorts, the lastAction filter and the ACTIVE_30D and INACTIVE_90D quick views |
| `quickView` | query | string | no | Portal users: ALL (the default), ACTIVE_30D, INACTIVE_90D or NEVER_SIGNED_IN |
| `lastAction` | query | string | no | Portal users with the activity: DEAL_REGISTRATION, COURSE_COMPLETED, CERTIFICATE_ISSUED, EVENT_RSVP or NONE |
| `portalRole` | query | string | no | Portal users: ADMIN or MEMBER |
| `page` | query | integer | no | Zero-based page, of partner groups or of rows |
| `pageSize` | query | integer | no | Groups (1 to 100) or rows (1 to 200) a page, default 25 |

## Responses

### 200 — OK: the groups (view group), the rows (view row) or the portal users (view row with portalAccess)

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

**`PrmOrgPartnerContactsPage`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `crmRead` | PrmPartnerCrmRead | no |  |
| `facets` | object | yes |  |
| `groups` | array<PrmOrgPartnerContactGroup> | yes |  |
| `page` | integer | yes |  |
| `pageSize` | integer | yes |  |
| `totalGroups` | integer | yes |  |
| `totals` | object | yes |  |

**`PrmPartnerCrmRead`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contactsWithheld` | integer | no | People on the Account with no email address, left out because the caller does not hold crm.read_record. |
| `message` | string | no | Why a FAILED read failed. |
| `status` | string | yes | OK, FAILED (only the contacts in Fours are listed) or NOT_LINKED |

**`PrmOrgPartnerContactGroup`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `canInvite` | boolean | yes | People can be invited into the partner's Fours workspace. |
| `champion` | object | yes |  |
| `counts` | object | yes |  |
| `crmAccountName` | string | no |  |
| `crmLinked` | boolean | yes |  |
| `crmProvider` | string | no |  |
| `partner` | PrmPartnerRef | yes |  |
| `partnerDomain` | string | no |  |
| `partnerManager` | string | no |  |
| `partnerOrgId` | string | no |  |
| `rows` | array<PartnerContact> | yes |  |
| `status` | string | yes |  |

**`PrmPartnerRef`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `name` | string | yes |  |

**`PartnerContact`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `apolloId` | string | no | ApolloID is the Apollo.io person ID for re-enrichment. |
| `crmContactId` | string | no | CrmContactID is the person's record under the linked CRM Account. |
| `email` | string | no | Email is the contact's verified email address. |
| `enrichedAt` | string | no | EnrichedAt is the RFC3339 timestamp of the last enrichment. |
| `firstName` | string | no |  |
| `id` | string | no | ID is the partnership_contact row id. Empty until someone acted on the person (added, edited, synced, removed); address such a person by email. |
| `invitationId` | string | no | InvitationID and InvitedAt describe the pending invitation when Portal is INVITED. |
| `invitedAt` | string | no |  |
| `isPrimary` | boolean | no | IsPrimary indicates this is the highest-seniority partnership contact. |
| `lastActivityAt` | string | no | LastActivityAt is the person's last sign-in to the partner portal. |
| `lastName` | string | no |  |
| `linkedinUrl` | string | no | LinkedinURL is the contact's LinkedIn profile URL. |
| `name` | string | no | Name is the contact's full name. |
| `ownDomain` | boolean | no | OwnDomain marks a person on the ISV's own email domain. Such rows are returned only with includeOwnDomain and are never synced, invited or made champion. |
| `phone` | string | no |  |
| `portal` | PrmContactPortalStatus | no |  |
| `role` | PrmContactRole | no |  |
| `seniority` | string | no | Seniority is the contact's seniority level (e.g., "vp", "director", "manager", "ic"). |
| `source` | PrmContactSource | no |  |
| `syncError` | string | no | SyncError is the CRM's error from the last failed sync, verbatim. |
| `syncStatus` | PrmContactSyncStatus | no |  |
| `title` | string | no | Title is the contact's job title/role (e.g., "VP of Partnerships"). |

### 400 — An unknown filter, sort or view, a filter or sort the view does not take, a page out of range, or partnerIds (renamed partnershipIds)

Content-Type: `text/plain`

### 500 — Internal server error

Content-Type: `text/plain`

## Example

_Generated from this operation's schema. Values are placeholders — substitute your own ids, and set `SUGER_TOKEN` to a bearer token from the [OAuth client-credentials exchange](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
curl -X GET 'https://api.suger.cloud/ai/org/{orgId}/prm/contact' \
  -H "Authorization: Bearer $SUGER_TOKEN"
```

### Response — 200

```json
{
  "facets": {
    "failed": 1,
    "firstFailure": {
      "email": "buyer@example.com",
      "error": "string",
      "partnerName": "Acme Corp",
      "partnershipId": "01H0000000000000000000"
    },
    "linkedPartnerIds": [
      "01H0000000000000000000"
    ],
    "listedRows": [
      {
        "count": 1,
        "id": "01H0000000000000000000",
        "name": "Acme Corp"
      }
    ],
    "ownDomainHidden": 1,
    "partners": [
      {
        "canInvite": true,
        "count": 1,
        "crmLinked": true,
        "domains": [
          "string"
        ],
        "id": "01H0000000000000000000",
        "name": "Acme Corp"
      }
    ]
  },
  "groups": [
    {
      "canInvite": true,
      "champion": {
        "email": "buyer@example.com",
        "name": "Acme Corp"
      },
      "counts": {
        "inFours": 1,
        "matches": 1,
        "ownDomainHidden": 1,
        "portalUsers": 1
      },
      "crmLinked": true,
      "partner": {
        "id": "01H0000000000000000000",
        "name": "Acme Corp"
      },
      "rows": [
        {
          "apolloId": "01H0000000000000000000",
          "crmContactId": "01H0000000000000000000",
          "email": "buyer@example.com",
          "enrichedAt": "string",
          "firstName": "Acme Corp",
          "id": "01H0000000000000000000",
          "invitationId": "01H0000000000000000000",
          "invitedAt": "2026-01-31T12:00:00Z",
          "isPrimary": true,
          "lastActivityAt": "2026-01-31T12:00:00Z",
          "lastName": "Acme Corp",
          "linkedinUrl": "https://example.com"
        }
      ],
      "status": "string",
      "crmAccountName": "Acme Corp",
      "crmProvider": "string",
      "partnerDomain": "string",
      "partnerManager": "string",
      "partnerOrgId": "01H0000000000000000000"
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalGroups": 1,
  "totals": {
    "partners": 1,
    "people": 1
  },
  "crmRead": {
    "status": "string",
    "contactsWithheld": 1,
    "message": "string"
  }
}
```

### Error — 400

```json
"string"
```

---

API reference: https://doc.fours.com/api/
