find_member_by_identity

Find the project member who connected a given account on a connector, from the connector key and the platform's own id.

Purpose

Turns the id a bot or a server hands over into a Subscriby member: give it the project, the connector the account lives on and the platform's own id for the account, and it answers the same row get_subscriber does, with the member's connected accounts embedded as identities[]. This is the lookup for a workflow that starts from a platform event (a message, a join, a role change) and needs to know which member, if any, that account belongs to. An account nobody in the project has connected is RESOURCE_NOT_FOUND, indistinguishable from an unknown project, so a caller never learns whether an id exists elsewhere. The REST twin is the identity filter on GET /v1/projects/{project}/members, which returns a one-row page instead.

Required ability

project-user:view-any

Input schema

{
  "type": "object",
  "required": ["project_id", "connector", "external_id"],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the project the member belongs to."
    },
    "connector": {
      "type": "string",
      "description": "Connector key the account lives on, as `list_connectors` lists them."
    },
    "external_id": {
      "type": "string",
      "description": "The platform's own id for the account, as `list_member_identities` shows it."
    }
  }
}

Output shape

{
  "data": {
    "id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
    "status": "customer",
    "name": "Ada Lovelace",
    "identities": [
      {
        "id": "6a1f0c3e-2d4b-4e8a-9c7d-1b5e3f9a2c4d",
        "connector": "telegram",
        "source": "handshake",
        "preferred": true,
        "external_id": "123456789",
        "display_name": "Ada Lovelace",
        "username": "ada",
        "linked_at": "2026-09-12T10:05:00Z"
      }
    ],
    "created_at": "2026-05-18T10:40:00Z"
  }
}

The row is the one get_subscriber and list_subscribers render; identities[] lists every account the member connected, not only the one asked about.

Example prompts

"Which member of project 7f3d1c92-… is the Telegram account 123456789?"

"A member wrote to the bot from account 123456789. Find them and tell me their subscription status."

Failure modes

RESOURCE_NOT_FOUND — unknown project_id, a project outside the token's scope, or an account nobody in the project has connected.
TOKEN_MISSING_ABILITY — token lacks project-user:view-any.