Relationship API
13 min
The Relationships API can be used to see how you and your users can best connect to the People and Organization in the Altrata dataset
It can also be used to see how these People and Organizations connect to each other
My Paths to Person and Organization
The myPathsToPerson and myPathsToOrganization can be used to retrieve paths from the current user to a target Person or Organization respectively. These paths are ordered by relevance, with the strongest paths returned first
The paths can begin in one of two ways:
- From an Altrata Person that the current user has added a Contact on the Altrata platform
- From an Altrata Person that another user under the same Account has added a Contact on the Altrata platform
If you have authenticated as a service user, only the later will be avalible as service users are unable to add contacts themselves
1st Degree Connection
If the Altrata Person who has been added as a contact is the target Person, or currently works at the target Organization, then this is a 1st degree connection
1st degree connections will always be returned first when the contact has been added by the current user
2nd Degree Connection
If the Altrata Person who has been added as a contact has a relationship with the target Person, or a Person who currently works at the target Organization, then this is a 2nd degree connection
Person Network
The Person Network query can be used to find all the People a given Person has a relationship with. These connections will always be at the 1st degree, giving you a complete picture of all the People the source Person has worked with over their career
Pathfinder
The API also contains queries to find paths between two entities. Currently the following permutations are supported:
- Person paths to Person - returns how one Altrata Person can connect to another.
- If the source Person has a relationship with the target Person, this is a 1st degree connection
- If the relationship goes via an intermeditary Person, this is a 2nd degree connection
- Person paths to Organization - returns how an Altrata Person can connect to an Altrata Organization
- If the Person currently works at the Organization, this is a direct connection
- If the Person has a relationship with someone who works at the Organization, this is a 1st degree connection
- If the Person has a relationship with an intermeditary Person who themslves knows somone who works at the Organization, this is a 2nd degree connection
- Organization paths to Organization - returns how one Altrata Organization can connect to another.
- If one Person currently works at both the source and target Organizations, this is a direct connection
- If a Person who currently works at the source Organization has a relationship with a Person two currently works at the target Organization, this is a 1st degree connection
- My Paths to Person - returns how the current user can connect to an Altrata Person, either via their own contributed contacts or their Colleagues contacts
- If the target Person has been added as a contact by the current user or one of their colleages, this is a 1st degree connection
- If the target Person has a relationship with a Person who has been added as a contact by the current user or one of their colleages, this is a 2nd degree connection
- My Paths to Organization - returns how the current user can connect to an Altrata Organization, either via their own contributed contacts or their Colleagues contacts to a Person who works at the Organization
- If a Person who works at the target Organization has been added as a contact by the current user or one of their colleages, this is a 1st degree connection
- If a Person who works at the target Organization has a relationship with a Person who has been added as a contact by the current user or one of their colleages, this is a 2nd degree connection
Example Queries
This document provides usage examples for the Relationships API
myPathsToPerson
Find the relationship paths from the authenticated user to a specific person.
query {
myPathsToPerson(
personId: "1-per-39571767"
userRelationshipType: [CONTACT, COLLEAGUE]
pageInfo: {
after: 0
first: 10
}
) {
... on MyPathsToPersonResponse {
start {
id
firstName
lastName
email
}
target {
id
name
rolePrimaryTitle
email
}
paths {
... on FirstDegreeUserToPersonPath {
entity1 {
id
firstName
lastName
}
relationship1 {
score
relationshipStrength
contactRelationshipsType
}
}
... on SecondDegreeUserToPersonPath {
entity1 {
id
firstName
lastName
}
relationship1 {
score
relationshipStrength
}
entity2 {
id
name
}
relationship2 {
score
relationshipStrength
overlapTypes
}
}
}
pageInfoResponse {
totalCount
pageInfo {
endCursor
}
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on UserNotFoundError {
userNotFoundErrorCode
errorMessage
correlationId
}
... on TargetNotFoundError {
targetNotFoundErrorCode
errorMessage
correlationId
}
... on AuthorizationError {
errorMessage
correlationId
authorizationErrorCode
}
}
}myPathsToOrganization
Find relationship paths from the authenticated user to a specific organization.
query {
myPathsToOrganization(
organizationId: "1-org-756705"
userRelationshipType: [CONTACT, COLLEAGUE]
pageInfo: {
after: 0
first: 10
}
) {
... on MyPathsToOrganizationResponse {
start {
id
firstName
lastName
email
}
target {
id
name
isRestricted
}
paths {
... on FirstDegreeUserToOrganizationPath {
entity1 {
id
firstName
lastName
}
relationship1 {
score
relationshipStrength
}
entity2 {
id
name
}
relationship2 {
score
relationshipStrength
roleTitle
email
}
}
... on SecondDegreeUserToOrganizationPath {
entity1 {
id
firstName
lastName
}
relationship1 {
score
relationshipStrength
}
entity2 {
id
name
}
relationship2 {
score
relationshipStrength
overlapTypes
}
entity3 {
id
name
}
relationship3 {
score
relationshipStrength
roleTitle
}
}
}
pageInfoResponse {
totalCount
pageInfo {
endCursor
}
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on UserNotFoundError {
userNotFoundErrorCode
errorMessage
correlationId
}
... on TargetNotFoundError {
targetNotFoundErrorCode
errorMessage
correlationId
}
... on AuthorizationError {
errorMessage
correlationId
authorizationErrorCode
}
}
}getOverlapDetails
Get detailed information about overlaps between pairs of people.
query {
getOverlapDetails(
input: [
{ personId1: "1-per-42076243", personId2: "1-per-39571767" }
{ personId1: "1-per-44346368", personId2: "1-per-39571767" }
]
) {
... on OverlapDetailsResponse {
overlapDetails {
person1 {
id
name
rolePrimaryTitle
}
person2 {
id
name
rolePrimaryTitle
}
overlap {
score
overlapTypes
relationshipStrength
additionalInfo
}
detailsByOrganization {
organization {
id
name
}
duration {
length
unit
isApproximate
}
details {
person1RoleTitle
person2RoleTitle
startDate {
date
datePrecision
displayDate
}
endDate {
date
datePrecision
displayDate
}
status
}
}
}
missingOverlaps {
personId1
personId2
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on TargetNotFoundError {
targetNotFoundErrorCode
errorMessage
correlationId
}
}
}personNetwork
Get the network of first-degree connections for a person.
query {
personNetwork(
sourcePersonId: "1-per-39571767"
userRelationshipType: [CONTACT, COLLEAGUE]
relationshipStrengths: [STRONG, MEDIUM]
pageInfo: {
after: 0
first: 20
}
) {
... on PersonNetworkResponse {
start {
id
name
rolePrimaryTitle
email
}
paths {
... on FirstDegreePersonToPersonPath {
relationship1 {
score
overlapTypes
relationshipStrength
additionalInfo
}
entity1 {
id
name
rolePrimaryTitle
email
}
}
}
pageInfoResponse {
totalCount
pageInfo {
endCursor
}
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on SourceNotFoundError {
sourceNotFoundErrorCode
errorMessage
correlationId
}
... on AuthorizationError {
errorMessage
correlationId
authorizationErrorCode
}
}
}personPathsToOrganization
Find relationship paths from a person to an organization.
query {
personPathsToOrganization(
sourcePersonId: "1-per-39571767"
targetOrganizationId: "1-org-756705"
pageInfo: {
after: 0
first: 10
}
) {
... on PersonPathsToOrganizationResponse {
start {
id
name
rolePrimaryTitle
email
}
target {
id
name
isRestricted
}
paths {
... on DirectPersonToOrganizationPath {
relationship1 {
score
relationshipStrength
roleTitle
email
}
}
... on FirstDegreePersonToOrganizationPath {
relationship1 {
score
overlapTypes
relationshipStrength
}
entity1 {
id
name
rolePrimaryTitle
}
relationship2 {
score
relationshipStrength
roleTitle
}
}
... on SecondDegreePersonToOrganizationPath {
relationship1 {
score
overlapTypes
relationshipStrength
}
entity1 {
id
name
}
relationship2 {
score
overlapTypes
relationshipStrength
}
entity2 {
id
name
}
relationship3 {
score
relationshipStrength
roleTitle
}
}
}
pageInfoResponse {
totalCount
pageInfo {
endCursor
}
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on SourceNotFoundError {
sourceNotFoundErrorCode
errorMessage
correlationId
}
... on TargetNotFoundError {
targetNotFoundErrorCode
errorMessage
correlationId
}
... on AuthorizationError {
errorMessage
correlationId
authorizationErrorCode
}
}
}organizationPathsToOrganization
Find relationship paths between two organizations.
query {
organizationPathsToOrganization(
sourceOrganizationId: "1-org-756705"
targetOrganizationId: "1-org-9563464"
pageInfo: {
after: 0
first: 10
}
) {
... on OrganizationPathsToOrganizationResponse {
start {
id
name
isRestricted
}
target {
id
name
isRestricted
}
paths {
... on DirectOrganizationToOrganizationPath {
relationship1 {
score
relationshipStrength
roleTitle
}
entity1 {
id
name
rolePrimaryTitle
}
relationship2 {
score
relationshipStrength
roleTitle
}
}
... on FirstDegreeOrganizationToOrganizationPath {
relationship1 {
score
relationshipStrength
roleTitle
}
entity1 {
id
name
}
relationship2 {
score
overlapTypes
relationshipStrength
}
entity2 {
id
name
}
relationship3 {
score
relationshipStrength
roleTitle
}
}
... on SecondDegreeOrganizationToOrganizationPath {
relationship1 {
score
relationshipStrength
roleTitle
}
entity1 {
id
name
}
relationship2 {
score
overlapTypes
relationshipStrength
}
entity2 {
id
name
}
relationship3 {
score
overlapTypes
relationshipStrength
}
entity3 {
id
name
}
relationship4 {
score
relationshipStrength
roleTitle
}
}
}
pageInfoResponse {
totalCount
pageInfo {
endCursor
}
}
}
... on GenericError {
genericErrorCode
errorMessage
correlationId
}
... on SourceNotFoundError {
sourceNotFoundErrorCode
errorMessage
correlationId
}
... on TargetNotFoundError {
targetNotFoundErrorCode
errorMessage
correlationId
}
... on AuthorizationError {
errorMessage
correlationId
authorizationErrorCode
}
}
}personPathsToPerson
Find relationship paths between two People.