--- title: Relationship API slug: relationship-api docTags: createdAt: 2026-01-14T13:50:16.520Z --- The Altrata Relationships API is a GraphQL API for discovering how people and organizations are connected — through Altrata's relationship graph and through your own uploaded network of contacts. Use it to find warm introductions to a person, ways into an organization, shared history between two people, and the leadership connections between companies. This guide explains what each query does, what to expect in its results, how results are ordered, and the limits that apply. **Field and parameter reference** — for complete definitions of every parameter, filter, field, and enum, see the Data Dictionary on this documentation site. ## How Relationship Strength Is Determined Every relationship in a path carries a relative strength — `WEAK`, `MEDIUM`, or `STRONG`, exposed on the `relationshipStrength` field. Strength is not assessed the same way for every relationship: each relationship type is rated on the qualities that make that kind of connection genuinely meaningful. The paths in this guide are built from five relationship types; select `__typename` on a path's relationship fields to see which one you have received. `Contact`** — a contact uploaded by you or a colleague.** Strength reflects the connection strength recorded when the contact was uploaded: contacts marked with a high connection strength rate as strong, mid-range values as moderate, and contacts uploaded without a connection strength are treated as weak. `Overlap`** — shared history between two people in Altrata's relationship graph.** The `overlapTypes` field lists the kinds of shared history behind the relationship — `ROLE` for having worked together, and `FAMILY` for family ties, where family connections are enabled for your account — and a single `Overlap` can carry more than one; each additional strand of shared history increases the strength. A `ROLE` overlap is assessed on the seniority of the positions both people held, how long their time together lasted, and how recently it ended — two board members who overlapped for years until recently is a far stronger signal than two junior employees who overlapped briefly long ago. A `FAMILY` overlap is assessed on the closeness of the tie — spousal relationships rate highest, then parent–child, then siblings — and family relationships are always strong. `WorksAt`** — a person's employment at an organization.** For a current role, strength reflects the seniority of the position: chief executives, board members, and other executives rate strongest, descending through senior management to junior roles. Seniority is assessed from the role title, taking the full title into account rather than relying on a single keyword. Some queries also match past roles; a past role's strength reflects how recently it ended, declining steadily as time passes, and the relationship reflects the most senior role the person held at the organization. `InNetwork`** — a person's membership in a connection source enabled for your account**, such as a shared network. Strength reflects the basis of the membership. Current employment is the strongest form. Previous employment reflects the most senior role the person held at the organization, and its strength reflects how recently that role concluded, declining steadily as time passes; where the end of a role is unknown, the relationship is treated as weak. Shared education is rated at a fixed moderate strength — every alumnus of an institution rates alike. `InList`** — a person's or organization's membership in one of your curated lists.** Every member of a list rates alike, at a fixed strength. Path strength combines the strength of every relationship in the chain — a single weak link weakens the whole path, so a path is never stronger than its weakest relationship. Where queries rank by strength, longer paths rank below shorter paths of comparable strength, so a long chain of moderate connections does not outrank one strong direct connection. How each query uses strength in its ranking is described in its **How results are ordered** block. ## Your Paths to a Person or Organization These queries start from *you* — they search your own contacts, your colleagues' contacts, and any connection sources enabled for your account. ### myPathsToPerson **What it does** — returns a paginated collection of paths that connect you and your colleagues to a given person (`personId`), ordered by the overall strength of the path. **Returns** — `MyPathsToPersonResponse`: `start` is you (`Me`), `target` is the person you looked up, `paths` is a `UserToPersonPath` list, plus `pageInfoResponse`. Five path types are returned; the union's sixth member, `ThirdDegreeUserToPersonPath`, is not returned. `FirstDegreeUserToPersonPath` — a direct contact: the person you looked up is already a contact of yours or a colleague's. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> T(["target: Person"]) ``` `SecondDegreeUserToPersonPath` — through one intermediary: a contact of yours or a colleague's shares an overlap with the person. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> T(["target: Person"]) ``` `FirstDegreeNetworkToPersonPath` — when your account has a shared network: the person is a member of it. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> T(["target: Person"]) ``` `SecondDegreeNetworkToPersonPath` — when your account has a shared network: a network member shares an overlap with the person. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> T(["target: Person"]) ``` `ThirdDegreeNetworkToPersonPath` — when your account has a shared network: a network member reaches the person through two successive overlaps. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> I(["entity3: Person"]) I -- "relationship3: Overlap" --> T(["target: Person"]) ``` **How results are ordered** — strongest paths first; directness only breaks ties between equal strengths, so a strong path through an intermediary can outrank a weak direct contact, and a strong two-intermediary path from a connection source can outrank weaker shorter paths. Your paths and your colleagues' paths rank together, on strength alone; `myTopPathsToPerson` is the view that prioritizes your own paths. If connection sources enabled for your account reach the target more than one way — directly, or through the same intermediary — only the strongest of those is kept; paths through different intermediaries are kept separately, as are paths through your own and each colleague's contacts. For example: | Rank | Path | Why it ranks here | | ---- | ----------------------------------------------------------- | ------------------------------------------------------------------- | | 1 | You → Henrik (strong) → Priya (strong) | Two strong links make a strong path overall. | | 2 | Network → Sofia (strong) → Marcus (strong) → Priya (strong) | Longer, but strength decides — it outranks the weak direct contact. | | 3 | You → Priya (weak direct contact) | Direct, but weak — strength wins here. | ### myTopPathsToPerson **What it does** — returns a curated "top paths" view of your account's routes to a person (`personId`): direct-contact paths grouped together, and intermediary paths grouped by intermediary. A group is one intermediary plus the users (you or colleagues) who can reach them; direct-contact paths form a single group of their own, with the person you looked up counting as that group's unique person. `desiredUniquePersonCount` controls how many groups you get (the direct-contact group takes one of those slots) and `maxUsersPerPerson` caps the group size. **Returns** — `MyTopPathsToPersonResponse`: `start` (`Me`), `target` (`Person`), and `paths` (`UserToPersonPath` — the same five path shapes as `myPathsToPerson`; see its diagrams). No `pageInfoResponse`. **How results are ordered** — priority grouping comes before strength: your own direct contact paths form their own priority group, ahead of colleagues' paths, and paths found through connection sources enabled for your account that reflect current employment are shown first. Stronger paths rank higher only within a group. Paths reaching the person through two successive overlaps from a connection source sit in the lowest priority group, and each distinct pair of intermediaries on such a path forms a group of its own, taking one of the slots allowed by `desiredUniquePersonCount`. Duplicate routes from connection sources enabled for your account are merged into a single path. For example: | Rank | Path | Why it ranks here | | ---- | ----------------------------------------------------------- | -------------------------------------------------------- | | 1 | You → Priya (medium direct contact) | Your own contacts form a higher priority group. | | 2 | Marcus (colleague) → Priya (strong) | Stronger, but strength only counts within a group. | | 3 | Network → Sofia (strong) → Henrik (strong) → Priya (strong) | Two-intermediary paths sit in the lowest priority group. | ### myPathsToOrganization **What it does** — returns a paginated collection of paths that connect you and your colleagues to a given organization (`organizationId`), through people who work there. **Returns** — `MyPathsToOrganizationResponse`: `start` (`Me`), `target` (`Organization`), `paths` (`UserToOrganizationPath`), `pageInfoResponse`. Five path types are returned; the union's sixth member, `ThirdDegreeUserToOrganizationPath`, is not returned. `FirstDegreeUserToOrganizationPath` — a direct contact who works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: WorksAt" --> T(["target: Organization"]) ``` `SecondDegreeUserToOrganizationPath` — through one intermediary: a contact shares an overlap with someone who works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> P(["entity3: Person"]) P -- "relationship3: WorksAt" --> T(["target: Organization"]) ``` `FirstDegreeNetworkToOrganizationPath` — when your account has a shared network: a network member works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: WorksAt" --> T(["target: Organization"]) ``` `SecondDegreeNetworkToOrganizationPath` — when your account has a shared network: a network member shares an overlap with someone who works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> P(["entity3: Person"]) P -- "relationship3: WorksAt" --> T(["target: Organization"]) ``` `ThirdDegreeNetworkToOrganizationPath` — when your account has a shared network: a network member reaches someone at the organization through two successive overlaps. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> I(["entity3: Person"]) I -- "relationship3: Overlap" --> P(["entity4: Person"]) P -- "relationship4: WorksAt" --> T(["target: Organization"]) ``` **How results are ordered** — strongest paths first, with directness breaking ties, as in `myPathsToPerson`. Your paths and your colleagues' paths rank together, on strength alone; `myTopPathsToOrganization` is the view that prioritizes your own paths. If connection sources enabled for your account reach the same person at the target organization more than one way, only the strongest of those paths is kept — so a longer route through two overlaps appears only when it reaches a person at the organization that no shorter path from those sources reaches; paths through your own and each colleague's contacts are kept separately. ### myTopPathsToOrganization **What it does** — returns a curated "top paths" view of your account's routes to an organization (`organizationId`), grouped by the person at that organization. A group is one intermediary plus the users (you or colleagues) who can reach them. As with `myTopPathsToPerson`, `desiredUniquePersonCount` controls how many groups you get and `maxUsersPerPerson` caps the group size. **Returns** — `MyTopPathsToOrganizationResponse`: `start` (`Me`), `target` (`Organization`), `paths` (`UserToOrganizationPath` — the same five path shapes as `myPathsToOrganization`; see its diagrams). No `pageInfoResponse`. **How results are ordered** — paths that reach the organization through a member of one of your person lists lead the response, those through a current role at the organization ahead of those through a former role. Every other path follows, strongest first, with your own paths listed ahead of colleagues' when strengths tie. Where several routes from connection sources enabled for your account reach the same person at the organization, only the strongest is kept, so a longer route through two overlaps appears only when it reaches a person no shorter route from those sources reaches. ## Paths Between Any Two Entities These queries connect any two people or organizations through Altrata's relationship graph — they do not depend on your uploaded contacts. ### personPathsToPerson **What it does** — returns a paginated collection of paths that connect one person (`sourcePersonId`) to another (`targetPersonId`), either directly (a shared-history overlap) or through one intermediary. **Returns** — `PersonPathsToPersonResponse`: `start` and `target` are the two people, `paths` is a `PersonToPersonPath` list, plus `pageInfoResponse`. The two path types: `FirstDegreePersonToPersonPath` — a direct overlap between the two people; `entity1` is the target person. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> T(["entity1: Person"]) ``` `SecondDegreePersonToPersonPath` — through one intermediary who overlaps with both people. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> I(["entity1: Person"]) I -- "relationship2: Overlap" --> T(["target: Person"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — closer paths first: direct overlaps always come before paths through an intermediary, even when the intermediary path is stronger. Within each group, stronger paths come first. For example: | Rank | Path | Why it ranks here | | ---- | ----------------------------------------- | -------------------------------------------------- | | 1 | Ingrid → Daniel (medium direct overlap) | Direct always beats going through an intermediary. | | 2 | Ingrid → Sofia (strong) → Daniel (strong) | Stronger overall, but one step longer. | ### personPathsToOrganization **What it does** — returns a paginated collection of paths that connect a person (`sourcePersonId`) to an organization (`targetOrganizationId`): their own employment there, or routes through one or two intermediaries to someone who works there. **Returns** — `PersonPathsToOrganizationResponse`: `start` (`Person`), `target` (`Organization`), `paths` (`PersonToOrganizationPath`), `pageInfoResponse`. The three path types: `DirectPersonToOrganizationPath` — the person works at the target organization themselves. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: WorksAt" --> T(["target: Organization"]) ``` `FirstDegreePersonToOrganizationPath` — an overlap with someone who works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> I(["entity1: Person"]) I -- "relationship2: WorksAt" --> T(["target: Organization"]) ``` `SecondDegreePersonToOrganizationPath` — two overlaps in a row reach someone who works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> I(["entity1: Person"]) I -- "relationship2: Overlap" --> J(["entity2: Person"]) J -- "relationship3: WorksAt" --> T(["target: Organization"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — closer paths first: the person's own employment at the target always leads (direct paths are not strength-scored), then paths through one intermediary, then through two. Within each group, stronger paths come first. ### organizationPathsToOrganization **What it does** — returns a paginated collection of paths that connect one organization (`sourceOrganizationId`) to another (`targetOrganizationId`): a person who works at both, or an overlap between an employee of each. **Returns** — `OrganizationPathsToOrganizationResponse`: `start` and `target` are the two organizations, `paths` is an `OrganizationToOrganizationPath` list, plus `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreeOrganizationToOrganizationPath`, is not returned. `DirectOrganizationToOrganizationPath` — one person holds roles at both organizations; the path reads from the source organization through that person to the target. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> P(["entity1: Person"]) P -- "relationship2: WorksAt" --> T(["target: Organization"]) ``` `FirstDegreeOrganizationToOrganizationPath` — an overlap between an employee of each organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> P(["entity1: Person"]) P -- "relationship2: Overlap" --> Q(["entity2: Person"]) Q -- "relationship3: WorksAt" --> T(["target: Organization"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — paths through a person who works at both organizations always come first (they are not strength-scored), followed by paths through an overlap between employees, strongest first. ## Exploring a Person's Network These queries dig into one person's own relationships — who they know, and the shared history behind each connection. ### personNetwork **What it does** — returns a paginated view of a given person's (`sourcePersonId`) network: each person in their network appears once, with the single overlap relationship connecting them to the person you looked up. **Returns** — `PersonNetworkResponse`: `start` is the person you looked up; `paths` is a `PersonPath` list, plus `pageInfoResponse`. Every path is a `FirstDegreePersonToPersonPath` — one `Overlap` per network member, with `entity1` the network member. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> M(["entity1: Person"]) ``` **How results are ordered** — strongest overlaps first. ### getOverlapDetails **What it does** — returns the detailed shared history behind the `Overlap` relationships between pairs of people: where and when they worked together, and family ties. Accepts multiple pairs in one call via `input`, each with `personId1` and `personId2`. **Returns** — `OverlapDetailsResponse`: `overlapDetails` holds one entry per resolved pair — `person1`, `person2`, the `overlap` relationship, and the shared history behind it (`detailsByOrganization` for `ROLE` overlaps, `familyDetails` for `FAMILY`); `missingOverlaps` lists the pairs for which no overlap details could be found. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR P1(["person1: Person"]) -- "overlap: Overlap" --> P2(["person2: Person"]) ``` **How results are ordered** — the order of results is not guaranteed for this query; contact Altrata support if you need ordering guarantees. ## Leadership Connections This group maps the connections organizations have through their boards and leadership teams. ### seniorLeadersToOrganizations **What it does** — returns the senior leaders (board members and leadership team) of a source organization (`sourceOrganizationId`), and for each leader, the other organizations where they also hold senior positions. **Returns** — `SeniorLeadersToOrganizationsResponse`: `sourceOrganization`, plus `paths` (`[SeniorLeadershipPath!]!`). Each path is one leader: `leadership` holds their role at the source organization, and `otherLeaderships` their roles elsewhere. Both are `SeniorLeaderOfOrganization` objects — `person`, `organization`, and `relationship` (`SeniorLeaderOf`: `roleId`, `roleTitle`, and `seniority`, the seniority classification of the role). ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR L(["person: Person"]) -- "leadership: SeniorLeaderOf" --> S(["sourceOrganization: Organization"]) L -- "otherLeaderships: SeniorLeaderOf" --> O(["otherLeaderships: Organization"]) ``` **How results are ordered** — leaders are listed alphabetically by name, and each leader's other positions alphabetically by organization name. Position in the list carries no meaning about strength or importance. ## Your Contacts and Network These queries list the people already in your account's network — useful for syncing, deduplicating, or seeding lookups with `personId` values. ### myContacts **What it does** — returns the Altrata person IDs of your own contacts. **Returns** — `MyContactsResponse.contactIds` (`[String!]!`). **How results are ordered** — the IDs are returned in no particular order — do not infer meaning from position. ### myColleaguesContacts **What it does** — returns the contacts of your colleagues (other users in your account): a flat ID list, plus a detailed list of who holds each contact. **Returns** — `MyColleaguesContactsResponse`: `colleaguesContactsIds` (`[String!]!`) and `colleaguesContacts` (`[UserContact!]`), where each `UserContact` has the `person`, the `user` who holds the contact (`Me` or `Colleague`), and the `contact` relationship. **How results are ordered** — the results are returned in no particular order — do not infer meaning from position. ### myNetwork **What it does** — returns a paginated collection of the members of your combined network: your contacts, your colleagues' contacts, and any connection sources enabled for your account. `userNetworkType` restricts the results to a single membership type; depending on the type you select, the members are people or organizations. `searchName` narrows the collection to members whose name contains the given text, ignoring case. **Returns** — `MyNetworkResponse`: `networkMembers`, each carrying the `id` of the person or organization, and `pageInfoResponse`. With `userNetworkType: COLLEAGUE` each member also carries the `person` and the `contacts` held by your colleagues — for each, the colleague (`user`) and the `contact` relationship with its strength. Your account must share contacts between its users for the `COLLEAGUE` type to return members. **How results are ordered** — members are returned in ascending order of `id`, so paging through the collection is consistent from one request to the next; position in the list carries no meaning about strength or importance. The exception is `userNetworkType: COLLEAGUE`, which returns one member per person ordered by name, with each person's `contacts` listed strongest first and then by colleague name. ## Reports These queries package pathfinding results and a person's network into shareable files. ### downloadPathfinderReport **What it does** — generates a pathfinder report (the paths between a source and a target) as a downloadable file and returns a signed download URL; report downloads must be enabled for your account. `reportTemplate` names the report as `SOURCE_TO_TARGET` and determines what kind of ID `sourceId` and `targetId` expect: `PERSON` takes an Altrata person ID, `ORGANIZATION` an organization ID, and `PERSON_LIST` / `ORGANIZATION_LIST` the ID of one of your curated lists; for `MY_NETWORK` (source side only), contact Altrata support for the value to supply in `sourceId`. Check the `PathfinderReportTemplate` enum via introspection for the full set of templates. **Returns** — `DownloadPathfinderReportResponse.downloadUrl` (`String!`): a signed URL from which to download the generated report. **Limits** — a report includes at most 400 paths. **How results are ordered** — the ordering of paths inside the generated report is not guaranteed; contact Altrata support if you need ordering guarantees. ### downloadPersonNetworkReport **What it does** — generates a report of a person's (`sourceId`) entire first-degree network — the same network `personNetwork` returns — as a downloadable file and returns a signed download URL; report downloads and person-network access must both be enabled for your account. `reportFormat` selects `PDF` or `CSV`. `userRelationshipType` restricts the report to network members who are your own contacts, your colleagues' contacts, or both. **Returns** — `DownloadPersonNetworkReportResponse.downloadUrl` (`String!`): a signed URL from which to download the generated report. **Limits** — a report includes at most 400 network members. **How results are ordered** — the ordering of network members inside the generated report is not guaranteed; contact Altrata support if you need ordering guarantees. ## List Pathfinding These queries find paths to (or from) a **list** — a user-curated collection of people or organizations, identified by a list ID. Responses follow the same `start` / `paths` / `target` / `pageInfoResponse` pattern as the queries above. Lists appear as `PersonList` / `OrganizationList` objects (`listId`, `listName`). Whatever the starting point, every path ends with an `InList` relationship into the target list. **How results are ordered** — by default these queries return closer paths first, with stronger paths first within each level. The two `my…List` queries deviate, as described in their sections. ### personPathsToPersonList **What it does** — returns a paginated collection of paths that connect a person (`sourcePersonId`) to a person list (`targetPersonListId`). **Returns** — `PersonPathsToPersonListResponse`: `start` (`Person`), `target` (`PersonList`), `paths` (`PersonToPersonListPath`), `pageInfoResponse`. The three path types: `DirectPersonToPersonListPath` — the person is in the list themselves. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: InList" --> T(["target: PersonList"]) ``` `FirstDegreePersonToPersonListPath` — a direct overlap with a list member. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> M(["entity1: Person"]) M -- "relationship2: InList" --> T(["target: PersonList"]) ``` `SecondDegreePersonToPersonListPath` — a list member is reached through one intermediary. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> I(["entity1: Person"]) I -- "relationship2: Overlap" --> M(["entity2: Person"]) M -- "relationship3: InList" --> T(["target: PersonList"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### organizationPathsToPersonList **What it does** — returns a paginated collection of paths that connect an organization (`sourceOrganizationId`) to a person list (`targetPersonListId`). **Returns** — `OrganizationPathsToPersonListResponse`: `start` (`Organization`), `target` (`PersonList`), `paths` (`OrganizationToPersonListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreeOrganizationToPersonListPath`, is not returned. `DirectOrganizationToPersonListPath` — a list member works at the organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> M(["entity1: Person"]) M -- "relationship2: InList" --> T(["target: PersonList"]) ``` `FirstDegreeOrganizationToPersonListPath` — an overlap between someone at the organization and a list member. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> P(["entity1: Person"]) P -- "relationship2: Overlap" --> M(["entity2: Person"]) M -- "relationship3: InList" --> T(["target: PersonList"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### myPathsToPersonList **What it does** — returns a paginated collection of paths that connect you and your colleagues to a person list (`personListId`). **Returns** — `MyPathsToPersonListResponse`: `start` (`Me`), `target` (`PersonList`), `paths` (`UserToPersonListPath`), `pageInfoResponse`. The four path types: `FirstDegreeUserToPersonListPath` — a contact of yours or a colleague's is in the list. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: InList" --> T(["target: PersonList"]) ``` `SecondDegreeUserToPersonListPath` — a contact shares an overlap with a list member. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> M(["entity3: Person"]) M -- "relationship3: InList" --> T(["target: PersonList"]) ``` `FirstDegreeNetworkToPersonListPath` — when your account has a shared network: a network member is in the list. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: InList" --> T(["target: PersonList"]) ``` `SecondDegreeNetworkToPersonListPath` — when your account has a shared network: a network member shares an overlap with a list member. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> M(["entity3: Person"]) M -- "relationship3: InList" --> T(["target: PersonList"]) ``` **How results are ordered** — closeness still comes first. Within the same closeness, your own paths come first; next come paths from connection sources enabled for your account — those reflecting current employment first, then past employment and shared education; then colleagues' paths. Strength decides only within each of those groups. ### personListPathsToPersonList **What it does** — returns a paginated collection of paths that connect one person list (`sourcePersonListId`) to another (`targetPersonListId`). **Returns** — `PersonListPathsToPersonListResponse`: `start` and `target` are the two `PersonList` objects, `paths` (`PersonListToPersonListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreePersonListToPersonListPath`, is not returned. `DirectPersonListToPersonListPath` — a person is in both lists. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: PersonList"]) -- "relationship1: InList" --> M(["entity1: Person"]) M -- "relationship2: InList" --> T(["target: PersonList"]) ``` `FirstDegreePersonListToPersonListPath` — an overlap between a member of each list. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: PersonList"]) -- "relationship1: InList" --> M(["entity1: Person"]) M -- "relationship2: Overlap" --> P(["entity2: Person"]) P -- "relationship3: InList" --> T(["target: PersonList"]) ``` **Limits** — page size is capped at 50 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### personPathsToOrganizationList **What it does** — returns a paginated collection of paths that connect a person (`sourcePersonId`) to an organization list (`targetOrganizationListId`). **Returns** — `PersonPathsToOrganizationListResponse`: `start` (`Person`), `target` (`OrganizationList`), `paths` (`PersonToOrganizationListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreePersonToOrganizationListPath`, is not returned. `DirectPersonToOrganizationListPath` — the person works at a listed organization themselves. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: WorksAt" --> O(["entity1: Organization"]) O -- "relationship2: InList" --> T(["target: OrganizationList"]) ``` `FirstDegreePersonToOrganizationListPath` — an overlap with someone who works at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Person"]) -- "relationship1: Overlap" --> P(["entity1: Person"]) P -- "relationship2: WorksAt" --> O(["entity2: Organization"]) O -- "relationship3: InList" --> T(["target: OrganizationList"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### organizationPathsToOrganizationList **What it does** — returns a paginated collection of paths that connect an organization (`sourceOrganizationId`) to an organization list (`targetOrganizationListId`). **Returns** — `OrganizationPathsToOrganizationListResponse`: `start` (`Organization`), `target` (`OrganizationList`), `paths` (`OrganizationToOrganizationListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreeOrganizationToOrganizationListPath`, is not returned. `DirectOrganizationToOrganizationListPath` — a person works at both the organization and a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> P(["entity1: Person"]) P -- "relationship2: WorksAt" --> O(["entity2: Organization"]) O -- "relationship3: InList" --> T(["target: OrganizationList"]) ``` `FirstDegreeOrganizationToOrganizationListPath` — an overlap between an employee of the organization and someone at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Organization"]) -- "relationship1: WorksAt" --> P(["entity1: Person"]) P -- "relationship2: Overlap" --> Q(["entity2: Person"]) Q -- "relationship3: WorksAt" --> O(["entity3: Organization"]) O -- "relationship4: InList" --> T(["target: OrganizationList"]) ``` **Limits** — page size is capped at 500 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### myPathsToOrganizationList **What it does** — returns a paginated collection of paths that connect you and your colleagues to an organization list (`organizationListId`). **Returns** — `MyPathsToOrganizationListResponse`: `start` (`Me`), `target` (`OrganizationList`), `paths` (`UserToOrganizationListPath`), `pageInfoResponse`. In this query, the `WorksAt` hop into the listed organization may reflect a current or a past role. The four path types: `FirstDegreeUserToOrganizationListPath` — a contact of yours or a colleague's works at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: WorksAt" --> O(["entity3: Organization"]) O -- "relationship3: InList" --> T(["target: OrganizationList"]) ``` `SecondDegreeUserToOrganizationListPath` — a contact shares an overlap with someone at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> U(["entity1: User"]) U -- "relationship1: Contact" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> P(["entity3: Person"]) P -- "relationship3: WorksAt" --> O(["entity4: Organization"]) O -- "relationship4: InList" --> T(["target: OrganizationList"]) ``` `FirstDegreeNetworkToOrganizationListPath` — when your account has a shared network: a network member works at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: WorksAt" --> O(["entity3: Organization"]) O -- "relationship3: InList" --> T(["target: OrganizationList"]) ``` `SecondDegreeNetworkToOrganizationListPath` — when your account has a shared network: a network member shares an overlap with someone at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: Me"]) --> N(["entity1: Network"]) N -- "relationship1: InNetwork" --> C(["entity2: Person"]) C -- "relationship2: Overlap" --> P(["entity3: Person"]) P -- "relationship3: WorksAt" --> O(["entity4: Organization"]) O -- "relationship4: InList" --> T(["target: OrganizationList"]) ``` **How results are ordered** — closeness still comes first. Within the same closeness, your own paths come first, those through a current role at the listed organization ahead of those through a past role; next come paths from connection sources enabled for your account — those reflecting past employment first, then current employment and shared education; then colleagues' paths, again current roles ahead of past roles. Strength decides only within each of those groups. ### personListPathsToOrganizationList **What it does** — returns a paginated collection of paths that connect a person list (`sourcePersonListId`) to an organization list (`targetOrganizationListId`). **Returns** — `PersonListPathsToOrganizationListResponse`: `start` (`PersonList`), `target` (`OrganizationList`), `paths` (`PersonListToOrganizationListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreePersonListToOrganizationListPath`, is not returned. `DirectPersonListToOrganizationListPath` — a list member works at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: PersonList"]) -- "relationship1: InList" --> M(["entity1: Person"]) M -- "relationship2: WorksAt" --> O(["entity2: Organization"]) O -- "relationship3: InList" --> T(["target: OrganizationList"]) ``` `FirstDegreePersonListToOrganizationListPath` — a list member's overlap with someone at a listed organization. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: PersonList"]) -- "relationship1: InList" --> M(["entity1: Person"]) M -- "relationship2: Overlap" --> P(["entity2: Person"]) P -- "relationship3: WorksAt" --> O(["entity3: Organization"]) O -- "relationship4: InList" --> T(["target: OrganizationList"]) ``` **Limits** — page size is capped at 50 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. ### organizationListPathsToOrganizationList **What it does** — returns a paginated collection of paths that connect one organization list (`sourceOrganizationListId`) to another (`targetOrganizationListId`). **Returns** — `OrganizationListPathsToOrganizationListResponse`: `start` and `target` are the two `OrganizationList` objects, `paths` (`OrganizationListToOrganizationListPath`), `pageInfoResponse`. Two path types are returned; the union's third member, `SecondDegreeOrganizationListToOrganizationListPath`, is not returned. `DirectOrganizationListToOrganizationListPath` — a person works at organizations in both lists. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: OrganizationList"]) -- "relationship1: InList" --> A(["entity1: Organization"]) A -- "relationship2: WorksAt" --> P(["entity2: Person"]) P -- "relationship3: WorksAt" --> O(["entity3: Organization"]) O -- "relationship4: InList" --> T(["target: OrganizationList"]) ``` `FirstDegreeOrganizationListToOrganizationListPath` — an overlap between employees of organizations in each list. ```mermaid %%{init: {"flowchart": {"useMaxWidth": false}}}%% flowchart LR S(["start: OrganizationList"]) -- "relationship1: InList" --> A(["entity1: Organization"]) A -- "relationship2: WorksAt" --> P(["entity2: Person"]) P -- "relationship3: Overlap" --> Q(["entity3: Person"]) Q -- "relationship4: WorksAt" --> O(["entity4: Organization"]) O -- "relationship5: InList" --> T(["target: OrganizationList"]) ``` **Selecting path types** — the response contains only the path types your query selects as inline fragments on `paths`. If you select only `FirstDegreeOrganizationListToOrganizationListPath`, you get only first degree paths, and pagination runs over those paths alone. A query that uses a named fragment on `paths` returns every path type. A query that selects no path type returns no paths and a `totalCount` of 0. **Limits** — page size is capped at 50 results; asking for more returns the cap. **How results are ordered** — the group default: closer paths first, with stronger paths first within each level. *** *Last updated: 2026-09-10*