Skip to content
Browse docslist_goal_matches

list_goal_matches

Reads a page of saved published match summaries for one of your goals.

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

Inputs#

InputRequiredDescription
goalIdyesExact owned goal UUID from a goal read
pageSizenoNonnegative integer; omitted or 0 means 20, capped at 100
pageTokennoReturned continuation token; omitted or empty starts the list

Keep the goal unchanged on continuation. Tokens are private, actor-bound, and expire after one hour. Restart if a token expires. These are live reads, not a snapshot across pages.

Returns#

{ "matches", "nextPageToken" }. Only an empty nextPageToken means completion, including when a page has no named matches. Follow every page before claiming complete coverage; otherwise report what you actually read. Missing and unowned goals return unavailable. A readable goal without current matches, including an ended goal, returns an empty collection.

Match fieldDescription
id, nameExact match ID and readable identity; unnamed external identities are omitted
route{ kind: "own_contact", personId } for your contact, or { kind: "through_member", connector: { memberId, name } }
contextcurrent or earlier; earlier does not mean assessed against edited wording
fitgoal_fit, potential_win_win, explicit_win_win, or null for an unassessed suggestion
introductionnot_requested, requested, or offered in the owner's current collection; connector summaries can also have sent or declined
ownOutreachnull, chosen, connected, or not_connected; the member's own choice/report, never inferred contact consent

Own contacts come first, then member suggestions and fit priority within each route kind, with match ID breaking ties. Separate connector paths retain separate IDs even when they name the same person.

Summaries contain no explanations, profile, or search status. Read get_goal_match using id before explaining why someone fits. Read get_goal_search for saved search status. Reading starts nothing and contacts nobody.

Example#

json
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "pageSize": 20
}

Result (synthetic data):

json
{
  "matches": [{
    "id": "00000000-0000-4000-a000-000000000002",
    "name": "Synthetic candidate",
    "route": { "kind": "through_member", "connector": { "memberId": "00000000-0000-4000-a000-000000000003", "name": "Synthetic connector" } },
    "context": "current",
    "fit": "potential_win_win",
    "introduction": "not_requested",
    "ownOutreach": null
  }],
  "nextPageToken": ""
}