> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update a persona > Change the fields you send and keep the rest: `{"tier_level": 2}` re-prioritises a persona without resending a definition you may not have at hand. A list you send replaces the saved one whole, so to add one country send the current `countries` plus the new one. `[]` clears a list, and `"profile_keywords": ""` removes the keyword expression. The change applies immediately to everything that searches or matches from this persona: Contact Search, PipeGen, Key Contacts, job change alerts and the persona badges on your lists. Already-stored contacts keep the persona matches they were given. At least one job title is required (`job_titles_includes` or `canonical_job_titles_includes_ids`): seniority and countries only narrow, so a persona with no title would match every contact at every company. Prefer canonical IDs over free text — a canonical title searches every language LinkedIn localizes it into, while the same words typed as free text reach far fewer profiles. A free-text title that exactly names a canonical one is resolved for you and reported in `promoted_to_canonical`. Returns the saved persona in the [List personas](/api-reference/personas/list-personas) shape. `warnings` names anything that makes the persona work against itself: an exclude that cancels an included title, seniority bands that reject the band an included title names, a title too ambiguous to resolve, a seniority value that names no band. The persona is saved regardless. Free: no credits. ## OpenAPI ````yaml /reference/openapi.yaml patch /v2/personas/{id} openapi: 3.1.0 info: title: Tamtam Public API version: 2.0.0 servers: - url: https://api.tamtam.ai/api security: [] paths: /v2/personas/{id}: patch: tags: - Personas summary: Update a persona description: >- Change the fields you send and keep the rest: `{"tier_level": 2}` re-prioritises a persona without resending a definition you may not have at hand. A list you send replaces the saved one whole, so to add one country send the current `countries` plus the new one. `[]` clears a list, and `"profile_keywords": ""` removes the keyword expression. The change applies immediately to everything that searches or matches from this persona: Contact Search, PipeGen, Key Contacts, job change alerts and the persona badges on your lists. Already-stored contacts keep the persona matches they were given. At least one job title is required (`job_titles_includes` or `canonical_job_titles_includes_ids`): seniority and countries only narrow, so a persona with no title would match every contact at every company. Prefer canonical IDs over free text — a canonical title searches every language LinkedIn localizes it into, while the same words typed as free text reach far fewer profiles. A free-text title that exactly names a canonical one is resolved for you and reported in `promoted_to_canonical`. Returns the saved persona in the [List personas](/api-reference/personas/list-personas) shape. `warnings` names anything that makes the persona work against itself: an exclude that cancels an included title, seniority bands that reject the band an included title names, a title too ambiguous to resolve, a seniority value that names no band. The persona is saved regardless. Free: no credits. operationId: update-persona parameters: - in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PersonaWriteBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PersonaWriteResultDto' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - apikeyAuth: [] - bearerAuth: [] components: schemas: PersonaWriteBody: additionalProperties: false properties: canonical_job_titles_excludes_ids: description: Canonical job title IDs to exclude. items: type: string type: array canonical_job_titles_includes_ids: description: >- Canonical job title IDs to include. Take them from canonical_job_titles_includes on a persona you read back. Prefer these over free text: a canonical title searches every language LinkedIn localizes it into. items: type: string type: array countries: description: >- ISO 3166-1 alpha-2 codes of the countries people must be in. Empty means every country. A value that is not a code is refused rather than stored: a persona filters on the profile's country code, so a country name matches nobody. examples: - - FR items: type: string type: array country_excludes: description: ISO 3166-1 alpha-2 codes of the countries to leave out. examples: - - BE items: type: string type: array criteria_only: description: >- true makes the persona a filter only: it still matches and scores contacts, but defines no people search and is rejected by People search's persona_id. Defaults to false on create. examples: - false type: boolean job_titles_excludes: description: >- Free-text words that remove a person entirely, matched as whole words. Never exclude a word that appears in a title you include ('engineer' beside 'Cloud Engineer' cancels it); warnings says when one does. examples: - - Intern items: type: string type: array job_titles_includes: description: >- Free-text job titles to include, matched as whole words against the title the person holds, case-insensitively. Unquoted words must all appear ('VP Sales' matches 'VP of Sales EMEA'); quote a phrase to require it whole. A title that exactly names a canonical one is resolved to it and reported in promoted_to_canonical. examples: - - Head of Sales items: type: string type: array name: description: Display name. Required on create. examples: - Head of Sales — France minLength: 1 type: string profile_keywords: description: >- Keyword expression matched against the whole LinkedIn profile (headline, About, every role's description, skills), for what a person works ON — use the job title fields for their role. AND and OR in capitals, quotes around phrases. NOT, and an OR inside brackets, are refused because the provider answers both wrongly. Send an empty string to remove the expression. examples: - '"supply chain" AND SAP' type: string seniority_excludes: description: >- Seniority bands to drop, read the same way. A title carrying no seniority signal is kept here too. examples: - - In Training items: type: string type: array seniority_includes: description: >- Seniority bands to keep, read from the job title by Tamtam's own classifier. A title carrying no seniority signal is always kept, so this narrows without discarding the unclassified. Empty keeps every band. A value naming no band is ignored and reported in warnings rather than refused. examples: - - Director items: type: string type: array tier_level: description: Priority tier, 1 = highest. Defaults to 1 on create. examples: - 1 format: int32 minimum: 1 type: integer usages: description: >- What the persona is used for: 'prospecting', 'closing_deals', or both. At least one. Defaults to both on create. examples: - - prospecting items: type: string minItems: 1 type: array type: object PersonaWriteResultDto: additionalProperties: false properties: persona: $ref: '#/components/schemas/GetPersonasPersonaDto' description: The persona as saved, in the same shape List personas returns. promoted_to_canonical: description: >- Free-text job titles that exactly named a canonical title and were resolved to it. Empty when none were. items: $ref: '#/components/schemas/PersonaPromotedTitleDto' type: - array - 'null' warnings: description: >- Anything that makes the saved persona work against itself: an exclude cancelling an included title, seniority bands rejecting the band an included title names, a title too ambiguous to resolve, a seniority value naming no band. Empty when nothing is wrong. items: type: string type: - array - 'null' required: - persona - promoted_to_canonical - warnings type: object ErrorModel: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object GetPersonasPersonaDto: additionalProperties: false properties: canonical_job_titles_excludes: description: Canonical job titles the persona rejects, resolved to their labels items: $ref: '#/components/schemas/PersonaJobTitleDto' type: - array - 'null' canonical_job_titles_includes: description: Canonical job titles the persona matches, resolved to their labels items: $ref: '#/components/schemas/PersonaJobTitleDto' type: - array - 'null' countries: description: Country codes the persona is scoped to examples: - - FR items: type: string type: - array - 'null' country_excludes: description: Country codes the persona excludes examples: - - BE items: type: string type: - array - 'null' criteria_only: description: >- True when the persona exists only to drive scoring criteria. Such a persona defines no people search and is rejected by People search's persona_id. examples: - false type: boolean id: description: Persona UUID examples: - b3c6f5e2-1234-4abc-9def-0123456789ab type: string job_titles_excludes: description: Free-text job titles the persona rejects examples: - - Intern items: type: string type: - array - 'null' job_titles_includes: description: Free-text job titles the persona matches examples: - - Head of Sales items: type: string type: - array - 'null' name: description: Persona name examples: - Head of Sales — France type: string profile_keywords: description: >- Keyword expression the persona narrows its searches by, matched against the whole LinkedIn profile (headline, About, every role and its description, skills). Null when the persona has none. Applied by People search whenever this persona is used, so a search scoped to this persona returns only people whose profile text matches. examples: - '"supply chain" AND SAP' type: string seniority_excludes: description: >- Seniority bands the persona rejects, judged the same way. A person whose title falls into one of these is dropped even when it also matches seniority_includes. A title carrying no seniority signal is kept, so this never removes the unclassified. examples: - - In Training items: type: string type: - array - 'null' seniority_includes: description: >- Seniority bands the persona keeps, judged by Tamtam from the job title. Applied to fetched results, never sent to a search provider. examples: - - Director items: type: string type: - array - 'null' tier_level: description: >- Priority tier the account assigned to this persona. Lower is more important. examples: - 1 format: int64 type: integer usages: description: >- What the account uses this persona for. Effective values: 'prospecting', 'closing_deals'. examples: - - prospecting items: type: string type: - array - 'null' required: - id - name - tier_level - countries - country_excludes - job_titles_includes - job_titles_excludes - canonical_job_titles_includes - canonical_job_titles_excludes - seniority_includes - seniority_excludes - criteria_only - usages type: object PersonaPromotedTitleDto: additionalProperties: false properties: canonical_title: description: The canonical title it was resolved to. examples: - Head of Sales type: string job_title: description: The free-text title as sent. examples: - Head of Sales type: string required: - job_title - canonical_title type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object PersonaJobTitleDto: additionalProperties: false properties: acronym: description: Common acronym for the title, when one exists examples: - CRO type: string function: description: Business function the title belongs to, when known examples: - Sales type: string id: description: >- Canonical job title ID. Pass it to People search as canonical_job_titles_includes_ids. examples: - b3c6f5e2-1234-4abc-9def-0123456789ab type: string title: description: English label of the canonical job title examples: - Head of Sales type: string required: - id - title type: object securitySchemes: apikeyAuth: description: Account API key passed in the Authorization header in: header name: Authorization type: apiKey bearerAuth: description: Bearer JWT obtained via the OAuth 2.1 authorization flow scheme: bearer type: http ````