Identity and IDs

The Partner API uses IDs that you own for mapped business resources. Meshi also returns opaque operational handles such as run_id, review_id, and match_id; use those only on the endpoints that document them, never as person identifiers. The deliberate person-addressing exception is an event-roster entity_id handle for pre-existing attendees that do not yet have a partner ID.

Partner-Owned ID Model

You choose these IDs:

Resource	Field
Event	event_id
Session	session_id
Attendee	attendee_id
Generic ID map entry	kind + partner_id

Use stable IDs from your source system. Do not generate a fresh ID each time you retry a create; that creates a different logical object.

ID Validation

Field	Pattern	Notes
kind	^[A-Za-z][A-Za-z0-9_-]{0,63}$	1-64 characters; starts with a letter.
partner_id, event_id, session_id, attendee_id	^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$	1-128 characters; letters, digits, ., _, :, and -.

Invalid kinds return 400 INVALID_PARTNER_KIND. Invalid IDs return 400 INVALID_PARTNER_ID.

Event-roster entity handles

GET /events/:event_id/attendees, readiness, and match responses include entity_id. An attendee added before the partner integration can have attendee_id: null and id_source: "meshi". Within that event, its returned entity_id is accepted only by:

• PATCH /events/:event_id/attendees/:attendee_id for side correction;
• per-attendee match lookup;
• ordered-pair match lookup; and
• repeated exclude_entity_ids[] match filters.

Attendee detail, identity history, per-attendee readiness, and deletion still require a partner attendee_id. A UUID from another event or org never broadens access.

Org Scoping

The org is derived from your API key. Every lookup is scoped to that org:

1. You submit a partner ID.
2. Meshi resolves it to the mapped internal record for your org.
3. Meshi checks access and visibility.
4. Meshi returns data using partner-facing IDs.

An ID that is valid in another org but not mapped in your org returns a not-found error rather than cross-org data.

Confirm an ID Mapping

Use GET /id-map/:kind/:partner_id to check whether an ID is mapped.

curl -sS "$MESHI_BASE/id-map/attendee/att-1001" \
  -H "Authorization: Bearer $MESHI_KEY"

Mapped response:

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

Unmapped IDs return 404 PARTNER_ID_NOT_FOUND.

Conflict Semantics

Creating a resource with an already-mapped ID returns 409 PARTNER_ID_CONFLICT. In an idempotent integration, treat that as “already provisioned” only after fetching the resource and confirming it is the same logical object.

Identity Reviews

Enrichment can produce identity ambiguity. Open reviews appear in either the org-wide queue or the event-scoped queue:

curl -sS "$MESHI_BASE/review-queue?limit=50" \
  -H "Authorization: Bearer $MESHI_KEY"

curl -sS "$MESHI_BASE/events/summit-2026/review-queue?limit=50" \
  -H "Authorization: Bearer $MESHI_KEY"

Resolve an open review with one of three decisions:

Decision	Meaning
accept	The candidate is the right person.
reject	The candidate is not the right person.
distinct	The held source row represents a separate person.

For a held import, terminal progress.errors[] includes the first actionable review_id. List the queue to see all candidate reviews for that partner_id. accept adopts the selected existing person; distinct creates a new person from the held row; reject returns remaining_reviews. Rejecting the final candidate returns 409 REJECT_LAST_CANDIDATE without consuming it, so choose distinct. Conflict-safe 409 responses leave the review open; list the queue again before retrying.

Each queue item includes a candidate comparison object with its available display_name, title, company, and linkedin_url. It intentionally excludes email addresses and Meshi internal IDs. Accept only when this evidence supports the same person; reject a clearly different candidate, or choose distinct when none of the candidates is the imported person.

curl -sS -X POST "$MESHI_BASE/review-queue/<REVIEW_ID>/resolve" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "distinct", "reason": "Confirmed as a separate attendee." }'

For duplicate people, merge the source partner ID into the target partner ID:

curl -sS -X POST "$MESHI_BASE/review-queue/<REVIEW_ID>/merge" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_kind": "attendee",
    "source_partner_id": "att-dupe",
    "target_kind": "attendee",
    "target_partner_id": "att-1001",
    "reason": "Same person in source system."
  }'

You can inspect a single attendee’s identity decision history:

curl -sS "$MESHI_BASE/events/summit-2026/attendees/att-1001/identity?limit=50" \
  -H "Authorization: Bearer $MESHI_KEY"

Decision history is ordered descending by created_at.