Browse docsget_goal_matches

`get_goal_matches`

Reads the saved matches for one of your goals.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

When to use it#

When you're asked who Gravity found for a goal. It reads matches that already exist. It starts no search and contacts nobody.

Inputs#

Input	Required	Type	Description
`goalId`	yes	string	UUID of a goal you own

Returns#

{ "goal", "search", "matches" }:

Field	Type	Description
`goal`	object	`{ id, text, beneficiary? }`. A missing or unowned goal returns the common `unavailable` error.
`search`	object or null	`{ runId, status, stage, activities, searchProgress, searchedMemberCount, groupMemberCount, incomplete }` for the search of the goal's current version. Null if the goal changed since it was last searched, or has ended.
`matches`	list	Your own contacts first, then matches through each connector, strongest first

incomplete identifies unfinished networks; stage, activities, and searchProgress describe the last saved progress. A readable goal with no matches returns matches: []; that is distinct from unavailable.

Each match has:

Field	Type	Description
`proposalId`	string	Match ID
`name`	string	The person's name. For your own contact without a saved name, their email address. Through a connector, "Potential connection" when no reliable name is known.
`route`	string	`people_you_know` for your own contact, or `through_member` when a fellow member could introduce you
`connectorName`	string or null	The member who could introduce you. Null for your own contacts.
`personId`	string or null	The person's ID in your Rolodex, for your own contacts. Null otherwise.
`headline`, `currentRole`, `linkedInUrl`	string or null	Public LinkedIn information, for matches through a connector
`summary`	string or null	Who the person is
`howTheyCouldHelp`	string or null	Why they could help with your goal
`whatYouCouldOffer`	string or null	Why meeting could be useful to them
`valueToYou`, `valueToThem`	string or null	Fit in each direction: `borderline_yes`, `clear_yes`, or `strong_yes`
`fitTier`	string or null	`goal_fit`, `potential_win_win`, or `explicit_win_win`
`goalContextStatus`	string	`current`, or `earlier` when the match was found for a previous version of the goal. `assessedGoalText` then holds that version's wording.
`connectorSuggestion`	string or null	When someone added this person by hand, their reason: the connector on a route through them, or you for your own contact on a goal for someone else
`introductionRequested`	boolean	You've already asked the connector for this introduction
`introductionOffered`	boolean	The connector offered an introduction that awaits your decision in Gravity

A match through a connector never includes the person's contact details, the connector's relationship with them, or how the connector knows them.

Example#

json

{
  "goalId": "00000000-0000-4000-a000-000000000001"
}

Result (synthetic data):

json

{
  "goal": {
    "id": "00000000-0000-4000-a000-000000000001",
    "text": "Find design partners",
    "beneficiary": null
  },
  "search": {
    "status": "running",
    "stage": "searching",
    "activities": [
      "researching"
    ],
    "searchProgress": {
      "estimatedPercent": 50,
      "completedNetworks": 1,
      "totalNetworks": 2,
      "completedTurns": 3
    },
    "runId": "00000000-0000-4000-a000-000000000002",
    "searchedMemberCount": 1,
    "groupMemberCount": 2,
    "incomplete": false
  },
  "matches": [
    {
      "proposalId": "00000000-0000-4000-a000-000000000002",
      "goalContextStatus": "current",
      "assessedGoalText": "Find design partners",
      "name": "Synthetic candidate",
      "route": "through_member",
      "connectorName": "Synthetic connector",
      "personId": null,
      "headline": "Public headline",
      "currentRole": "Public role",
      "linkedInUrl": null,
      "summary": "Possible design partner",
      "howTheyCouldHelp": "Could discuss the product",
      "whatYouCouldOffer": null,
      "valueToYou": "clear_yes",
      "valueToThem": null,
      "fitTier": "goal_fit",
      "connectorSuggestion": null,
      "introductionRequested": false,
      "introductionOffered": false
    }
  ]
}

When presenting a match, say what it is: "Gravity found a possible match through Sam." Don't say Sam can introduce you or that Jordan wants to meet. To ask for an introduction, open the goal in Gravity.

Matches and searches explains routes and searches.
start_goal_matching starts a new search.

get_goal_matches

When to use it#

Inputs#

Returns#

Example#

Related#

`get_goal_matches`