Relationship API

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.

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.

These queries start from you — they search your own contacts, your colleagues' contacts, and any connection sources enabled for your account.

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.

SecondDegreeUserToPersonPath — through one intermediary: a contact of yours or a colleague's shares an overlap with the person.

FirstDegreeNetworkToPersonPath — when your account has a shared network: the person is a member of it.

SecondDegreeNetworkToPersonPath — when your account has a shared network: a network member shares an overlap with the person.

ThirdDegreeNetworkToPersonPath — when your account has a shared network: a network member reaches the person through two successive overlaps.

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:

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:

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.

SecondDegreeUserToOrganizationPath — through one intermediary: a contact shares an overlap with someone who works at the organization.

FirstDegreeNetworkToOrganizationPath — when your account has a shared network: a network member works at the organization.

SecondDegreeNetworkToOrganizationPath — when your account has a shared network: a network member shares an overlap with someone who works at the organization.

ThirdDegreeNetworkToOrganizationPath — when your account has a shared network: a network member reaches someone at the organization through two successive overlaps.

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.

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.

These queries connect any two people or organizations through Altrata's relationship graph — they do not depend on your uploaded contacts.

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.

SecondDegreePersonToPersonPath — through one intermediary who overlaps with both people.

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:

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.

FirstDegreePersonToOrganizationPath — an overlap with someone who works at the organization.

SecondDegreePersonToOrganizationPath — two overlaps in a row reach someone who works at the 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.

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.

FirstDegreeOrganizationToOrganizationPath — an overlap between an employee of each 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.

These queries dig into one person's own relationships — who they know, and the shared history behind each connection.

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.

How results are ordered — strongest overlaps first.

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.

How results are ordered — the order of results is not guaranteed for this query; contact Altrata support if you need ordering guarantees.

This group maps the connections organizations have through their boards and leadership teams.

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

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.

These queries list the people already in your account's network — useful for syncing, deduplicating, or seeding lookups with personId values.

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.

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.

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.

These queries package pathfinding results and a person's network into shareable files.

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.

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.

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.

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.

FirstDegreePersonToPersonListPath — a direct overlap with a list member.

SecondDegreePersonToPersonListPath — a list member is reached through one intermediary.

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.

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.

FirstDegreeOrganizationToPersonListPath — an overlap between someone at the organization and a list member.

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.

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.

SecondDegreeUserToPersonListPath — a contact shares an overlap with a list member.

FirstDegreeNetworkToPersonListPath — when your account has a shared network: a network member is in the list.

SecondDegreeNetworkToPersonListPath — when your account has a shared network: a network member shares an overlap with a list member.

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.

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.

FirstDegreePersonListToPersonListPath — an overlap between a member of each list.

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.

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.

FirstDegreePersonToOrganizationListPath — an overlap with someone who works at a listed organization.

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.

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.

FirstDegreeOrganizationToOrganizationListPath — an overlap between an employee of the organization and someone at a listed organization.

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.

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.

SecondDegreeUserToOrganizationListPath — a contact shares an overlap with someone at a listed organization.

FirstDegreeNetworkToOrganizationListPath — when your account has a shared network: a network member works at a listed organization.

SecondDegreeNetworkToOrganizationListPath — when your account has a shared network: a network member shares an overlap with someone at a listed organization.

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.

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.

FirstDegreePersonListToOrganizationListPath — a list member's overlap with someone at a listed organization.

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.

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.

FirstDegreeOrganizationListToOrganizationListPath — an overlap between employees of organizations in each list.

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