Relationship API

queries below are a list of available queries you can use to retrieve data from the relationships api getoverlapdetails returns the shared employment history of two people that defines the overalp relationships between them possible return objects overlapdetailsresponse genericerror targetnotfounderror arguments field type description required input overlapdetailsinput\[]! a collection of person pairs that you wish to retrieve the overalp details of yes organizationpathstoorganization returns a paginated collection of paths that connect one organization to another, ordered by the overall strength of the path possible return objects organizationpathstoorganizationresponse genericerror sourcenotfounderror targetnotfounderror authorizationerror arguments field type description required sourceorganizationid string! the altrata id of the organization to find paths from yes targetorganizationid string! the altrata id of the organization to find paths to yes pageinfo pageinfoinput pagination input no mypathstoorganization returns a paginated collection of paths that connect the current user to a given organization, ordered by the overall strength of the path possible return objects mypathstoorganizationresponse genericerror usernotfounderror targetnotfounderror authorizationerror arguments field type description required organizationid string! the altrata id of the organization to find paths to yes userrelationshiptype userrelationshiptypeenum\[] when provided paths will be filtered to only include those of the given types no pageinfo pageinfoinput pagination input no mypathstoperson returns a paginated collection of paths that connect the current user to a given person, ordered by the overall strength of the path possible return objects mypathstopersonresponse genericerror usernotfounderror targetnotfounderror authorizationerror arguments field type description required personid string! the altrata id of the person to find paths to yes userrelationshiptype userrelationshiptypeenum\[] when provided paths will be filtered to only include those of the given types no pageinfo pageinfoinput pagination input no mytoppathstoorganization returns a collection of paths that connect the current user to a given organization, with 1st degree paths grouped together and 2nd degree paths grouped by intermiditary person the number of groups to return and the size of the groups can be controlled by the desireduniquepersoncount and maxusersperperson arguments respectively possible return objects mytoppathstoorganizationresponse genericerror usernotfounderror targetnotfounderror authorizationerror arguments field type description required organizationid string! the altrata id of the organization to find paths to yes desireduniquepersoncount int! the number of groups to return may return fewer than the number specified here if there are not enough paths to build the desired number of groups yes maxusersperperson int! the max size of each group for each group may return fewer than the number specified here if there are not enough paths to fill the group to the desired size yes mytoppathstoperson returns a collection of paths that connect the current user to a given person, with 1st degree paths grouped together and 2nd degree paths grouped by intermiditary person the number of groups to return and the size of the groups can be controlled by the desireduniquepersoncount and maxusersperperson arguments respectively possible return objects mytoppathstopersonresponse genericerror usernotfounderror targetnotfounderror authorizationerror arguments field type description required personid string! the altrata id of the person to find paths to yes desireduniquepersoncount int! the number of groups to return may return fewer than the number specified here if there are not enough paths to build the desired number of groups yes maxusersperperson int! the max size of each group for each group may return fewer than the number specified here if there are not enough paths to fill the group to the desired size yes personnetwork returns a paginated set of overlap relationships that a given person has to other people possible return objects personnetworkresponse genericerror sourcenotfounderror authorizationerror arguments field type description required sourcepersonid string! the altrata id of the person to find paths from yes userrelationshiptype userrelationshiptypeenum\[] when provided paths will be filtered to only include those of the given types no relationshipstrengths relationshipstrengthenum\[] when provided paths will be filtered to only include those of the given relative strengths no pageinfo pageinfoinput pagination input no personpathstoorganization returns a paginated collection of paths that connect a person to an organization, ordered by the overall strength of the path possible return objects personpathstoorganizationresponse genericerror sourcenotfounderror targetnotfounderror authorizationerror arguments field type description required sourcepersonid string! the altrata id of the person to find paths from yes targetorganizationid string! the altrata id of the organization to find paths to yes pageinfo pageinfoinput pagination input no personpathstoperson returns a paginated collection of paths that connect one person to another, ordered by the overall strength of the path possible return objects personpathstopersonresponse genericerror sourcenotfounderror targetnotfounderror authorizationerror arguments field type description required sourcepersonid string! the altrata id of the person to find paths from yes targetpersonid string! the altrata id of the person to find paths to yes pageinfo pageinfoinput pagination input no objects the following objects describe the structure of the data you’ll receive from the api, including field names, data types, and what each field represents colleague represents a user under the same account as the current user implements entity, user field type description id string! the id of the user firstname string the first name name of the user lastname string the last name name of the user role string the role the user has accountname string the name of the altrata account the user belongs to email string the email address of the user contact indicates a user knows a person in some capacity, as they have added the person as a contact on the altrata platform implements relationship field type description contactrelationshipstype string how the user said they knew the person when they added them as a contact, for example “colleague”, “friend”, “family” relationshipstrength relationshipstrengthenum! indicates the relative strength of this relationships this value is self contributed by the user when they add the person as a contact dateinformation field type description date string! the raw date in the format yyyy mm dd for partial dates some components may be missing, this is indicated by the dateprecision field dateprecision durationunit! indicates whether this is a complete or partial date, and if partial how complete it is displaydate string! a formatted date to display to users directorganizationtoorganizationpath field type description relationship1 worksat! details of the relationship between the source organization and the person in entity1 entity1 person! a person who works at the source organization and the target organization relationship2 worksat! details of the relationship between the person in entity1 and the target organization directpersontoorganizationpath field type description relationship1 worksat! details of the relationship between the source person and the target organization indicates the source person has a current role at the target organization duration field type description length int! the length of the duration unit durationunit! the unit the length integer is in isapproximate boolean! whether this duration is accurate or an estimation durationunit value description day represents a day month represents a month year represents a year entity base object representing an identifiable object in the relationships dataset field type description id string! the id of the entity firstdegreeorganizationtoorganizationpath field type description relationship1 worksat! details of the relationship between the source organization and the person in entity1 entity1 person! a person who works at the source organization who has an overlap relationship with a person who works at the target organization relationship2 overlap! details of the relationship between the person in entity1 and person in entity2 entity2 person! a person who works at the target organization who has an overlap relationship with a person who works at the source organization relationship3 worksat! details of the relationship between the person in entity2 and the target organization firstdegreepersontoorganizationpath field type description relationship1 overlap! details of the relationship between the source person and the person in entity1 entity1 person! a person who works at the target organization that the source person has an overlap relationship with relationship2 worksat! details of the relationship between the person in entity1 and the target organization firstdegreepersontopersonpath field type description relationship1 overlap! details of the relationship between the source person and the person in entity1 entity1 person! a person that the source person has an overlap relationship with firstdegreeusertoorganizationpath field type description entity1 user! the user who has added the person in entity2 who this path goes through as a contact will be of type me if the user is the same as the user querying the api, colleague if the user is a different user under the same account as the querying user paths via users outside of the querying user’s account will never be displayed relationship1 contact! details of the relationship between the user and the person in entity2 this path goes through entity2 person! a person who has a works at the target organization relationship2 worksat! details of the relationship between the person in entity2 and the target organization firstdegreeusertopersonpath field type description entity1 user! the user who has added the person this path goes to as a contact will be of type me if the user is the same as the user querying the api, colleague if the user is a different user under the same account as the querying user paths via users outside of the querying user’s account will never be displayed relationship1 contact! details of the relationship between the user and the person this path goes to me represents the current user that the query is being issued on the behalf of implements entity, user field type description id string! the id of the user firstname string the first name name of the user lastname string the last name name of the user role string the role the user has accountname string the name of the altrata account the user belongs to email string the email address of the user missingoverlaps field type description person1 person! a person that makes up one side of this overlap relationship person2 person! the person that makes up the other side of this overlap relationship mypathstoorganizationresponse field type description start me! the current user, from who the paths in this response originate paths usertoorganizationpath\[]! a collection of paths from the start user to the target organization will be of type firstdegreeusertoorganizationpath if the user or their colleagues have added a person who works at the organization as a contact, seconddegreeusertopersonpath if a person who works at the target organization has an overlap relationship with a person who has been added by the user or their colleague as a contact target organization! the organization that the paths in this response go to pageinforesponse pageinforesponse! information about pagination in a paged set of results mypathstopersonresponse field type description start me! the current user, from who the paths in this response originate paths usertopersonpath\[]! a collection of paths from the start user to the target person will be of type firstdegreeusertopersonpath if the user or their colleagues have added the person as a contact, seconddegreeusertopersonpath if a person the target has an overlap relationship with has been added by the user or their colleague as a contact target person! the person that the paths in this response go to pageinforesponse pageinforesponse! information about pagination in a paged set of results mytoppathstoorganizationresponse field type description start me! the current user, from who the paths in this response originate paths usertoorganizationpath\[]! a collection of paths from the start user to the target organization will be of type firstdegreeusertoorganizationpath if the user or their colleagues have added a person who works at the organization as a contact, seconddegreeusertopersonpath if a person who works at the target organization has an overlap relationship with a person who has been added by the user or their colleague as a contact target organization! the organization that the paths in this response go to mytoppathstopersonresponse field type description start me! the current user, from who the paths in this response originate paths usertopersonpath\[]! a collection of paths from the start user to the target person will be of type firstdegreeusertopersonpath if the user or their colleagues have added the person as a contact, seconddegreeusertopersonpath if a person the target has an overlap relationship with has been added by the user or their colleague as a contact target person! the person that the paths in this response go to organization represents an organization profile from the altrata dataset implements entity field type description id string! the altrata id of the organization name string! the full display name of the organization isrestricted boolean! returns true if the organization belongs to an altrata universe that the querying user does not have access to when set to true, this indicates that some fields have been nulled out due to lack of access organizationoverlapdetails field type description organization organization! the organization that the role overlap occured at duration duration! how long the overlap lasted details overlapdetails\[]! details of the overlap this collection will contain one record per pair of overlapping roles the two people at the organization overlap indicates two people are likely to know each other in some way implements relationship field type description overlaptypes overlaptype\[]! indicates the way in which the two people may know each other currently the only possible value is role, indicating that these people both had roles at the same organization at the same time at some point in their careers relationshipstrength relationshipstrengthenum! indicates the relative strength of this relationship more senior roles are typically considered to be stronger overlapdetails field type description person1roletitle string the title of the role one person in this overlap had at the time the overlap occured person2roletitle string the title of the role the other person in this overlap had at the time the overlap occured startdate dateinformation details on when this overlap occured enddate dateinformation details on when this overlap finished, or whether it is still ongoing status string indicates whether this overlap has finished or is still ongoing overlapdetailsinput field type description personid1 string! the altrata id if a person that makes up one side of the requested overlap relationship personid2 string! the altrata id if a person that makes up the other side of the requested overlap relationship overlapdetailsresponse field type description overlapdetails overlapwithdertails\[]! details for each requested overalp that were successfully found in the dataset missingoverlaps missingoverlaps! any overlaps that could not be found in the dataset overlapwithdetails field type description person1 person! a person that makes up one side of this overlap relationship person2 person! the person that makes up the other side of this overlap relationship overlap overalp details of the relationship between the person in person1 and the person in person2 detailsbyorganization organizationoverlapdetails\[] details of the ovelap relationship broken down by each organization that the two people have or had roles at together pageinfoinput field type description after int record index to fetch results from first int total number of records to be returned in the results pageinfooutput field type description endcursor int the record index to continue from to fetch the next page pageinforesponse field type description totalcount int the total number of records that matched the input query requesting this field can cause a slower query response time pageinfo pageinfooutput! information about the pagination in a paged set of results person represents a person profile from the altrata dataset implements entity field type description id string! the altrata id of the person name string! the full display name of the person roleprimarytitle string the title of the person’s primary role roleprimaryorganization organization the organization that the person’s primary role is at email string the person’s email address isrestricted boolean! returns true if the person belongs to an altrata universe that the querying user does not have access to when set to true, this indicates that some fields have been nulled out due to lack of access personnetworkresponse field type description start person! the person whose network you are querying paths personpath\[]! a collection of paths to people that the start person has an overlap relationship with will be of type firstdegreepersontopersonpath pageinforesponse pageinforesponse! information about pagination in a paged set of results relationship base object representing the connection between two entities in the relationships dataset field type description relationshipstrength relationshipstrengthenum! indicates the relative strength of a relationship relationshipstrengthenum indicates the relative strength of a relationship value description weak this is considered to be a low value relationship medium this is considered to be a mid value relationship strong this is considered to be a high value relationship seconddegreepersontoorganizationpath field type description relationship1 overlap! details of the relationship between the source person and the person in entity1 entity1 person! a person that the source person has an overlap relationship with, who also has an overlap relationship with someone who works at the target organization relationship2 overlap! details of the relationship between the person in entity1 and the person in entity2 entity2 person! a person the person in entity1 has an overlap relationship with, who works at the target organization relationship3 worksat! details of the relationship between the person in entity2 and the target organization seconddegreepersontopersonpath field type description relationship1 overlap! details of the relationship between the source person and the person in entity1 entity1 person! a person that the source person has an overlap relationship with relationship2 overlap! details of the relationship between the person in entity1 and the target person seconddegreeusertoorganizationpath field type description entity1 user! the user who has added the person in entity2 who this path goes through as a contact will be of type me if the user is the same as the user querying the api, colleague if the user is a different user under the same account as the querying user paths via users outside of the querying user’s account will never be displayed relationship1 contact! details of the relationship between the user and the person in entity2 this path goes through entity2 person! a person who has been added as a contact by the user in entity1 and who has an overlap relationship with the person in entity3 relationship2 overlap! details of the relationship between the person in entity2 and the person in entity3 entity3 person! a person who has a works at the target organization relationship3 worksat! details of the relationship between the person in entity3 and the target organization seconddegreeusertopersonpath field type description entity1 user! the user who has added the person this path goes via as a contact will be of type me if the user is the same as the user querying the api, colleague if the user is a different user under the same account as the querying user paths via users outside of the querying user’s account will never be displayed relationship1 contact! details of the relationship between the user and the person this path goes via entity2 person! the person added as a contact by the user in entity1 who has an overlap relationship with the person this path goes to user represents a user of the altrata platform field type description id string! the id of the user firstname string the first name name of the user lastname string the last name name of the user role string the role the user has accountname string the name of the altrata account the user belongs to email string the email address of the user worksat indicates that a person has a current role at an organization implements relationship field type description roletitle string the title of the role that the person currently holds at the organization when the person has multiple roles at the organization, the title of the most senior role is displayed email string professional email address for the person at the organization relationshipstrength relationshipstrengthenum! indicates the relative strength of this relationship more senior roles are typically considered to be stronger