{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/mentio-dev/json-schema/mentio-dev-person-schema.json",
  "title": "Person",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/mentio-dev-people-api-openapi.yml#/components/schemas/Person",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Person id (aut_...): the canonical account. An account merged into someone resolves to that person."
    },
    "platform": {
      "type": "string",
      "enum": [
        "bluesky",
        "hackernews",
        "github",
        "stackoverflow",
        "devto",
        "reddit",
        "x",
        "youtube",
        "news",
        "linkedin",
        "tiktok",
        "instagram",
        "appstore",
        "googleplay",
        "trustpilot",
        "googlemaps",
        "rss"
      ],
      "description": "Platform of the canonical account; `accounts` lists every account."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Display name as of their newest post; null when the platform has none."
    },
    "handle": {
      "type": [
        "string",
        "null"
      ],
      "description": "Platform handle of the canonical account, formatted as the platform shows it."
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile URL of the canonical account."
    },
    "avatarUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The account id (aut_...); the canonical one equals the person id."
          },
          "platform": {
            "type": "string",
            "enum": [
              "bluesky",
              "hackernews",
              "github",
              "stackoverflow",
              "devto",
              "reddit",
              "x",
              "youtube",
              "news",
              "linkedin",
              "tiktok",
              "instagram",
              "appstore",
              "googleplay",
              "trustpilot",
              "googlemaps",
              "rss"
            ],
            "description": "Platform: bluesky, hackernews, github, stackoverflow, devto, reddit, x, youtube, news, linkedin, tiktok, instagram, appstore (App Store reviews), googleplay (Google Play reviews), trustpilot (Trustpilot reviews), googlemaps (Google reviews of a place), rss (RSS and Atom feeds a keyword reads)."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Display name as the platform reports it."
          },
          "handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Platform handle derived from the profile URL, formatted as the platform shows it."
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Profile URL."
          }
        },
        "required": [
          "id",
          "platform",
          "name",
          "handle",
          "url"
        ]
      },
      "description": "Every account this workspace treats as this person, the canonical one first."
    },
    "reach": {
      "type": "object",
      "properties": {
        "followers": {
          "type": [
            "integer",
            "null"
          ]
        },
        "following": {
          "type": [
            "integer",
            "null"
          ]
        },
        "posts": {
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "required": [
        "followers",
        "following",
        "posts"
      ],
      "description": "Platform counts as of their newest post; null where the platform has no such number."
    },
    "profile": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "bio": {
          "type": [
            "string",
            "null"
          ]
        },
        "company": {
          "type": [
            "string",
            "null"
          ]
        },
        "location": {
          "type": [
            "string",
            "null"
          ]
        },
        "website": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "Only when the person made it public on the platform."
        },
        "links": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "provider": {
                "type": "string",
                "minLength": 1
              },
              "url": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "provider",
              "url"
            ]
          },
          "description": "Other accounts the person lists on their profile."
        },
        "fetchedAt": {
          "type": "string",
          "description": "When the profile was read."
        }
      },
      "required": [
        "bio",
        "company",
        "location",
        "website",
        "email",
        "links",
        "fetchedAt"
      ],
      "description": "Public profile facts; null until looked up."
    },
    "stats": {
      "type": "object",
      "properties": {
        "mentions": {
          "type": "integer",
          "minimum": 0,
          "description": "Every match of theirs for this workspace, relevant or not."
        },
        "relevant": {
          "type": "integer",
          "minimum": 0,
          "description": "Of those, scored relevant."
        },
        "sentiment": {
          "type": "object",
          "properties": {
            "positive": {
              "type": "integer",
              "minimum": 0
            },
            "neutral": {
              "type": "integer",
              "minimum": 0
            },
            "negative": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "positive",
            "neutral",
            "negative"
          ]
        },
        "firstSeenAt": {
          "type": "string",
          "description": "Their oldest matched post."
        },
        "lastSeenAt": {
          "type": "string",
          "description": "Their newest matched post."
        }
      },
      "required": [
        "mentions",
        "relevant",
        "sentiment",
        "firstSeenAt",
        "lastSeenAt"
      ],
      "description": "Computed over this workspace's matches."
    },
    "annotations": {
      "type": "object",
      "properties": {
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "notes": {
          "type": "string"
        },
        "muted": {
          "type": "boolean",
          "description": "Their posts stay out of the feed and every channel; ingest and billing are untouched. Read with groupId it is that group's own mute, which hides them from the mentions of that group's keywords only."
        }
      },
      "required": [
        "tags",
        "notes",
        "muted"
      ],
      "description": "What this workspace wrote about the person."
    },
    "outreach": {
      "type": "object",
      "properties": {
        "owner": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "User id of the workspace member."
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            },
            "email": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "id",
            "name",
            "email"
          ],
          "description": "The teammate who owns the contact; null when nobody does, or the owner left the workspace."
        },
        "stage": {
          "type": "string",
          "enum": [
            "not_contacted",
            "contacted",
            "replied",
            "in_talks",
            "customer",
            "not_a_fit"
          ],
          "description": "Where your workspace stands with the person: not_contacted, contacted, replied, in_talks, customer or not_a_fit."
        },
        "lastContactedAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "The newest logged activity; null when nobody logged a contact."
        }
      },
      "required": [
        "owner",
        "stage",
        "lastContactedAt"
      ],
      "description": "Where your workspace stands with the person. The first logged activity claims an unowned person for whoever reached out and moves not_contacted to contacted."
    }
  },
  "required": [
    "id",
    "platform",
    "name",
    "handle",
    "url",
    "avatarUrl",
    "accounts",
    "reach",
    "profile",
    "stats",
    "annotations",
    "outreach"
  ]
}