---
title: "Update your annotations on a person"
method: PATCH
path: "/v1/people/{id}"
tags: ["People"]
---

# Update your annotations on a person

`PATCH /v1/people/{id}`

## Request

- Base URL: `https://api.mentio.dev`
- URL: `https://api.mentio.dev/v1/people/{id}`
- Auth: HTTP bearer

Tags, notes, mute, and the outreach owner (a workspace member; null clears) and stage, for your workspace only. Mute hides their posts from your feed and every channel; ingest and billing never change. With `groupId` the annotations are that keyword group's own: `muted` hides the person, and the accounts that group merged into them, from the mentions of that group's keywords only (feed, alerts and digests), and the group's tags show on those mentions next to the workspace's. A mute set without `groupId` hides them everywhere.

## Path parameters

- `id` string, required: Person id (aut_...).

## Query parameters

- `groupId` string: Scope to one keyword group (grp_...): only people who mentioned that group's keywords, with that group's own tags, notes, mute, merges, activities and segments. Omit for the whole workspace.

## Request body

- object: Omitted fields are untouched.
  - `tags` string[]: Replaces the whole list.
  - `notes` string
  - `muted` boolean: true hides their posts from the feed, the alerts and the digests; false shows them again. Without groupId, for every keyword of the workspace; with groupId, for the mentions of that group's keywords only, leaving the workspace's mute as it is.
  - `ownerId` string, nullable: The member who owns the contact (user id); null clears.
  - `stage` 'not_contacted' | 'contacted' | 'replied' | 'in_talks' | 'customer' | 'not_a_fit': Where your workspace stands with the person: not_contacted, contacted, replied, in_talks, customer or not_a_fit.

## Response `200`

The updated person

- Person
  - `id` string, required: Person id (aut_...): the canonical account. An account merged into someone resolves to that person.
  - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: Platform of the canonical account; `accounts` lists every account.
  - `name` string, nullable, required: Display name as of their newest post; null when the platform has none.
  - `handle` string, nullable, required: Platform handle of the canonical account, formatted as the platform shows it.
  - `url` string, nullable, required: Profile URL of the canonical account.
  - `avatarUrl` string, nullable, required
  - `accounts` object[], required: Every account this workspace treats as this person, the canonical one first.
    - `id` string, required: The account id (aut_...); the canonical one equals the person id.
    - `platform` 'bluesky' | 'hackernews' | 'github' | 'stackoverflow' | 'devto' | 'reddit' | 'x' | 'youtube' | 'news' | 'linkedin' | 'tiktok' | 'instagram' | 'appstore' | 'googleplay' | 'trustpilot' | 'googlemaps' | 'rss', required: 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` string, nullable, required: Display name as the platform reports it.
    - `handle` string, nullable, required: Platform handle derived from the profile URL, formatted as the platform shows it.
    - `url` string, nullable, required: Profile URL.
  - `reach` object, required: Platform counts as of their newest post; null where the platform has no such number.
    - `followers` integer, nullable, required
    - `following` integer, nullable, required
    - `posts` integer, nullable, required
  - `profile` object, nullable, required: Public profile facts; null until looked up.
    - `bio` string, nullable, required
    - `company` string, nullable, required
    - `location` string, nullable, required
    - `website` string, nullable, required
    - `email` string, nullable, required: Only when the person made it public on the platform.
    - `links` object[], required: Other accounts the person lists on their profile.
      - `provider` string, required
      - `url` string, uri, required
    - `fetchedAt` string, required: When the profile was read.
  - `stats` object, required: Computed over this workspace's matches.
    - `mentions` integer, required: Every match of theirs for this workspace, relevant or not.
    - `relevant` integer, required: Of those, scored relevant.
    - `sentiment` object, required
      - `positive` integer, required
      - `neutral` integer, required
      - `negative` integer, required
    - `firstSeenAt` string, required: Their oldest matched post.
    - `lastSeenAt` string, required: Their newest matched post.
  - `annotations` object, required: What this workspace wrote about the person.
    - `tags` string[], required
    - `notes` string, required
    - `muted` boolean, required: 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.
  - `outreach` object, required: 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.
    - `owner` object, nullable, required: The teammate who owns the contact; null when nobody does, or the owner left the workspace.
      - `id` string, required: User id of the workspace member.
      - `name` string, nullable, required
      - `email` string, nullable, required
    - `stage` 'not_contacted' | 'contacted' | 'replied' | 'in_talks' | 'customer' | 'not_a_fit', required: Where your workspace stands with the person: not_contacted, contacted, replied, in_talks, customer or not_a_fit.
    - `lastContactedAt` string, nullable, required: The newest logged activity; null when nobody logged a contact.

## Other responses

- `400`: Invalid body, or the owner is not a workspace member
- `401`: Missing or invalid API key
- `404`: No mention by this person in this scope, or no such group

---

[API](https://skmtc.dev/mentio/apis/mentio-api.md) · [All operations](https://skmtc.dev/mentio/apis/mentio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mentio/apis/mentio-api/revisions/b16a21d0ed02?raw)