Endpoint Reference

All paths are relative to the Partner API base URL. The scope listed for each endpoint is the minimum effective scope.

Every response body includes correlation_id. Every error uses the shared error envelope described in Errors and Limits.

Service Account

`GET /auth`

Scope: partner:read

Returns authenticated service-account details.

Response 200:

{
  "org_id": "<ORG_ID>",
  "principal_type": "service_account",
  "service_account_user_id": "<SERVICE_ACCOUNT_USER_ID>",
  "scopes": ["partner:read", "partner:write"],
  "correlation_id": "<CORRELATION_ID>"
}

Route-specific errors: auth and scope errors only.

ID Resolution

`GET /id-map/:kind/:partner_id`

Scope: partner:read

Confirms whether a partner ID is mapped in your org.

Path parameters:

Name	Description
`kind`	Partner ID kind, such as `event`, `session`, or `attendee`.
`partner_id`	Partner-owned ID.

Response 200:

{
  "kind": "attendee",
  "partner_id": "att-1001",
  "mapped": true,
  "correlation_id": "<CORRELATION_ID>"
}

Errors: 400 INVALID_PARTNER_KIND, 400 INVALID_PARTNER_ID, 404 PARTNER_ID_NOT_FOUND.

Events

`POST /events`

Scope: partner:write

Creates an event. You own event_id.

Request:

{
  "event_id": "summit-2026",
  "title": "Annual Partner Summit 2026",
  "description": "Two-day leadership summit",
  "start_date": "2026-09-10",
  "end_date": "2026-09-11",
  "timezone": "America/New_York",
  "visibility": "private",
  "url_slug": "summit-2026"
}

Field limits:

Field	Limit
`title`	Required, max 200 characters.
`description`	Optional, max 4000 characters.
`start_date`, `end_date`	Optional ISO date strings.
`timezone`	Optional, max 128 characters.
`visibility`	Optional, max 32 characters.
`url_slug`	Optional, max 128 characters.

Response 201: event object with event_id, details, timestamps, and correlation_id.

Errors: 400 INVALID_JSON, 400 INVALID_PARTNER_ID, 400 INVALID_TITLE, 400 INVALID_DESCRIPTION, 400 INVALID_START_DATE, 400 INVALID_END_DATE, 400 INVALID_TIMEZONE, 400 INVALID_VISIBILITY, 400 INVALID_URL_SLUG, 409 PARTNER_ID_CONFLICT.

`GET /events`

Scope: partner:read

Lists events ordered descending by created_at.

Query parameters: limit (1-100, default 50), cursor.

Response 200:

{
  "items": [
    {
      "event_id": "summit-2026",
      "title": "Annual Partner Summit 2026",
      "description": "Two-day leadership summit",
      "event_details": null,
      "objectives": null,
      "welcome_instructions": null,
      "start_date": "2026-09-10",
      "end_date": "2026-09-11",
      "timezone": "America/New_York",
      "visibility": "private",
      "url_slug": "summit-2026",
      "created_at": "<ISO_DATETIME>",
      "updated_at": "<ISO_DATETIME>"
    }
  ],
  "next_cursor": null,
  "correlation_id": "<CORRELATION_ID>"
}

Errors: org, auth, scope, and rate-limit errors.

`GET /events/:event_id`

Scope: partner:read

Returns one event.

Response 200: event object with context fields, timestamps, and correlation_id.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND.

`POST /events/:event_id/context`

Scope: partner:write

Updates event context. At least one field is required.

Request:

{
  "event_details": "Senior product and engineering leaders.",
  "objectives": "Maximize useful introductions.",
  "welcome_instructions": "Share your top goal for the event."
}

Each field is optional and capped at 4000 characters.

Response 200:

{
  "event_id": "summit-2026",
  "context": {
    "event_details": "Senior product and engineering leaders.",
    "objectives": "Maximize useful introductions.",
    "welcome_instructions": "Share your top goal for the event."
  },
  "correlation_id": "<CORRELATION_ID>"
}

Errors: 400 INVALID_PARTNER_ID, 400 INVALID_JSON, 400 INVALID_CONTEXT, 404 EVENT_NOT_FOUND.

`GET /events/:event_id/context`

Scope: partner:read

Returns event context.

Response 200: { event_id, context, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND.

Sessions

`POST /events/:event_id/sessions`

Scope: partner:write

Creates a session within an event. You own session_id.

Request:

{
  "session_id": "opening-keynote",
  "title": "Opening Keynote",
  "description": "Kickoff session",
  "start_timestamp": "2026-09-10T13:00:00Z",
  "end_timestamp": "2026-09-10T14:00:00Z"
}

Response 201: session object with session_id, event_id, metadata, timestamps, and correlation_id.

Errors: 400 INVALID_PARTNER_ID, 400 INVALID_TITLE, 400 INVALID_DESCRIPTION, 400 INVALID_START_TIMESTAMP, 400 INVALID_END_TIMESTAMP, 404 EVENT_NOT_FOUND, 409 PARTNER_ID_CONFLICT.

`GET /events/:event_id/sessions`

Scope: partner:read

Lists event sessions ordered ascending by start_timestamp.

Query parameters: limit, cursor.

Response 200: { items, next_cursor, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND.

`GET /events/:event_id/sessions/:session_id`

Scope: partner:read

Returns one session.

Response 200: session object with correlation_id.

Errors: 400 INVALID_PARTNER_ID, 404 SESSION_NOT_FOUND, 404 EVENT_NOT_FOUND.

Attendees

`GET /events/:event_id/attendees`

Scope: partner:read

Lists event attendees ordered ascending by partner_id.

Query parameters: limit, cursor.

Response 200:

{
  "items": [
    {
      "attendee_id": "att-1001",
      "event_id": "summit-2026",
      "display_name": "Jordan Lee",
      "title": "VP Product",
      "company": "Acme",
      "event": {
        "role_at_event": null,
        "visibility": null,
        "goal": null,
        "needs": null,
        "offers": null,
        "onboarded_at": null,
        "joined_at": null
      },
      "identity": {
        "review_required": false,
        "open_review_count": 0
      }
    }
  ],
  "next_cursor": null,
  "correlation_id": "<CORRELATION_ID>"
}

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND.

`PUT /events/:event_id/attendees:import`

Scope: partner:write

Imports attendees into an event. Async; returns a run.

Request:

{
  "idempotency_key": "<IDEMPOTENCY_KEY>",
  "webhook_url": "https://example.com/future-webhook",
  "attendees": [
    {
      "attendee_id": "att-1001",
      "name": "Jordan Lee",
      "email": "jordan@example.com",
      "linkedin_url": "https://www.linkedin.com/in/jordanlee",
      "title": "VP Product",
      "company": "Acme",
      "raw_data": { "source": "crm-export" }
    }
  ]
}

Per-attendee limits:

Field	Limit
`name`	Required, max 240 characters.
`email`	Optional, max 320 characters.
`linkedin_url`	Optional, max 2048 characters.
`title`	Optional, max 512 characters.
`company`	Optional, max 512 characters.
`raw_data`	Optional JSON object.

The attendees array must be non-empty, contain unique attendee_id values, and contain at most 50,000 rows by default.

Response 202 first call or 200 idempotent replay: run object with kind: "import".

Errors: 400 INVALID_PARTNER_ID, 400 INVALID_JSON, 400 INVALID_IDEMPOTENCY_KEY, 400 INVALID_ATTENDEES, 400 INVALID_ATTENDEE, 400 DUPLICATE_ATTENDEE_ID, 400 INVALID_ATTENDEE_NAME, 400 INVALID_ATTENDEE_EMAIL, 400 INVALID_ATTENDEE_LINKEDIN_URL, 400 INVALID_ATTENDEE_TITLE, 400 INVALID_ATTENDEE_COMPANY, 400 INVALID_ATTENDEE_RAW_DATA, 400 INVALID_WEBHOOK_URL, 404 EVENT_NOT_FOUND, 409 IDEMPOTENCY_KEY_CONFLICT, 413 PAYLOAD_TOO_LARGE.

`GET /events/:event_id/attendees/:attendee_id/identity`

Scope: partner:read

Returns identity decision history for one attendee, ordered descending by created_at.

Query parameters: limit, cursor.

Response 200: { event_id, attendee_id, items, next_cursor, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND, 404 ATTENDEE_NOT_FOUND.

Enrichment

`POST /events/:event_id/enrichment-runs`

Scope: partner:write

Triggers attendee enrichment for an event. Async; returns a run.

Request:

{
  "idempotency_key": "<IDEMPOTENCY_KEY>",
  "webhook_url": "https://example.com/future-webhook"
}

Response 202 first call or 200 idempotent replay: run object with kind: "enrichment" and progress counters.

Errors: 400 INVALID_PARTNER_ID, 400 INVALID_JSON, 400 INVALID_IDEMPOTENCY_KEY, 400 INVALID_WEBHOOK_URL, 404 EVENT_NOT_FOUND, 409 IDEMPOTENCY_KEY_CONFLICT.

Matching

`POST /events/:event_id/match-runs`

Scope: partner:write

Triggers an attendee matching run. Async; returns a run.

Request:

{
  "idempotency_key": "<IDEMPOTENCY_KEY>",
  "webhook_url": "https://example.com/future-webhook",
  "top_n": 10
}

top_n is optional, defaults to 10, and must be 1-50.

Response 202 first call or 200 idempotent replay: run object with kind: "match".

Errors: 400 INVALID_PARTNER_ID, 400 INVALID_JSON, 400 INVALID_IDEMPOTENCY_KEY, 400 INVALID_WEBHOOK_URL, 404 EVENT_NOT_FOUND, 409 IDEMPOTENCY_KEY_CONFLICT.

`GET /events/:event_id/attendees/:attendee_id/matches`

Scope: partner:read

Lists top matches for one attendee, ordered descending by final_score.

Query parameters: limit, cursor, optional run_id. If run_id is omitted, the latest terminal run is used.

Response 200: { event_id, attendee_id, run_id, items, next_cursor, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND, 404 ATTENDEE_NOT_FOUND, 404 MATCH_RUN_NOT_FOUND.

`GET /events/:event_id/matches`

Scope: partner:read

Lists matches across all attendee pairs for an event, ordered descending by final_score.

Query parameters: limit, cursor, optional run_id, optional session_id, optional goal.

Response 200: { event_id, run_id, items, next_cursor, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND, 404 SESSION_NOT_FOUND, 404 MATCH_RUN_NOT_FOUND.

`GET /events/:event_id/matches/:principal_partner_id/:target_partner_id`

Scope: partner:read

Returns one ordered pair match score.

Query parameters: optional run_id.

Response 200:

{
  "event_id": "summit-2026",
  "match_id": "<MATCH_ID>",
  "run_id": "<RUN_ID>",
  "principal_attendee_id": "att-1001",
  "target_attendee_id": "att-1002",
  "final_score": 0.87,
  "sub_scores": {
    "goal_complementarity": 0.9,
    "goal_needs_to_offers": 0.8,
    "goal_offers_to_needs": 0.7,
    "value_alignment": 0.6,
    "general_similarity": 0.5,
    "score_a_to_b": 0.85,
    "score_b_to_a": 0.82
  },
  "best_goal_match": { "score": 0.9, "direction": "needsToOffers" },
  "driving_goal_pair": { "score": 0.9, "direction": "needsToOffers" },
  "intent_strength": { "aToB": 0.6, "bToA": 0.4 },
  "input_hash": "<INPUT_HASH>",
  "algorithm_version": "<ALGORITHM_VERSION>",
  "policy_version": "<POLICY_VERSION>",
  "context_snapshot_id": "<CONTEXT_SNAPSHOT_ID>",
  "freshness": { "computed_at": "<ISO_DATETIME>" },
  "computed_at": "<ISO_DATETIME>",
  "correlation_id": "<CORRELATION_ID>"
}

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND, 404 ATTENDEE_NOT_FOUND, 404 MATCH_RUN_NOT_FOUND, 404 MATCH_NOT_FOUND.

Goal IDs are not exposed. best_goal_match and driving_goal_pair surface score and direction only; goal text lives on attendee fields.

Runs

`POST /runs`

Scope: partner:write

Creates a generic run outside event scope.

Request:

{
  "kind": "import",
  "idempotency_key": "<IDEMPOTENCY_KEY>",
  "progress": {},
  "snapshot_metadata": {},
  "version_metadata": {},
  "webhook_url": "https://example.com/future-webhook"
}

kind must be import, enrichment, or match.

Response 201 first call or 200 idempotent replay: run object. event_id is null for non-event runs.

Errors: 400 INVALID_JSON, 400 INVALID_RUN_KIND, 400 INVALID_IDEMPOTENCY_KEY, 400 INVALID_PROGRESS, 400 INVALID_SNAPSHOT_METADATA, 400 INVALID_VERSION_METADATA, 400 INVALID_WEBHOOK_URL.

`GET /runs`

Scope: partner:read

Lists all runs for the org, ordered descending by created_at.

Query parameters: limit, cursor, optional kind.

Response 200: { items, next_cursor, correlation_id }.

Errors: 400 INVALID_RUN_KIND.

`GET /runs/:run_id`

Scope: partner:read

Polls one run. This is the canonical terminal-status poll for import, enrichment, and match runs.

Path parameters: run_id.

Response 200:

{
  "run_id": "<RUN_ID>",
  "kind": "match",
  "status": "queued",
  "event_id": "summit-2026",
  "idempotency_key": "<IDEMPOTENCY_KEY>",
  "progress": {},
  "error": null,
  "snapshot_metadata": {},
  "version_metadata": {},
  "webhook_url": null,
  "created_at": "<ISO_DATETIME>",
  "updated_at": "<ISO_DATETIME>",
  "started_at": null,
  "terminal_at": null,
  "correlation_id": "<CORRELATION_ID>"
}

Errors: 400 INVALID_RUN_ID, 404 RUN_NOT_FOUND.

Review Queue

`GET /events/:event_id/review-queue`

Scope: partner:read

Lists open identity reviews for one event’s attendees, ordered descending by created_at.

Query parameters: limit, cursor.

Response 200: { items, next_cursor, correlation_id }.

Errors: 400 INVALID_PARTNER_ID, 404 EVENT_NOT_FOUND.

`GET /review-queue`

Scope: partner:read

Lists open identity reviews across the org, ordered descending by created_at.

Query parameters: limit, cursor.

Response 200: { items, next_cursor, correlation_id }.

Route-specific errors: auth and scope errors only.

`POST /review-queue/:review_id/resolve`

Scope: partner:write

Accepts, rejects, or marks an open review as a distinct person.

Request:

{
  "decision": "accept",
  "reason": "Confirmed by source system operator."
}

decision must be accept, reject, or distinct.

Response 200: { review_id, kind, partner_id, decision, logged: true, minted, correlation_id }.

Errors: 400 INVALID_REVIEW_ID, 400 INVALID_JSON, 400 INVALID_REVIEW_DECISION, 404 REVIEW_NOT_FOUND.

`POST /review-queue/:review_id/merge`

Scope: partner:write

Resolves a review by merging the source entity into the target entity.

Request:

{
  "source_kind": "attendee",
  "source_partner_id": "att-dupe",
  "target_kind": "attendee",
  "target_partner_id": "att-1001",
  "reason": "Same person in source system."
}

Response 200: { review_id, source, target, merged: true, superseded_anchors, rewritten_anchors, deleted_computations, correlation_id }.

Errors: 400 INVALID_REVIEW_ID, 400 INVALID_JSON, 400 INVALID_PARTNER_KIND, 400 INVALID_PARTNER_ID, 400 REVIEW_SOURCE_MISMATCH, 400 MERGE_REJECTED, 404 REVIEW_NOT_FOUND, 404 PARTNER_ID_NOT_FOUND.