> ## Documentation Index > Fetch the complete documentation index at: https://docs.agile-tools.io/llms.txt > Use this file to discover all available pages before exploring further. # Update person > Patch person mutable fields using JSON Merge Patch semantics. Omitted fields stay unchanged. Explicit null clears only managerId, externalId, and jobTitle. Explicit null for other fields is rejected with validation error. Resolve organizationalUnitId via GET /v1/public/organizational-units and managerId via GET /v1/public/people. ## OpenAPI ````yaml /openapi.v1.local.json patch /v1/public/people/{id} openapi: 3.0.3 info: title: Agile Tools Public API description: >- REST API for integrating external systems with Agile Tools. ## Authentication Most endpoints require an `X-API-Key` header containing a valid owner-typed API key. Supported ownership types are `ORGANIZATION`, `PERSON`, and `VALUE_UNIT`. Anonymous library browsing endpoints use short-lived session tokens instead. ## Scope Behavior Wildcard scope (`*`) is organization-only. Value-unit keys are restricted to value-unit-centric endpoint families and descendant scope checks. Personal keys default to personal-empty scope unless explicit permissions are granted. Cross-organization key governance is out of scope for `/v1/public/*` and is handled by `/v1/sys/public-api-keys`. ## Rate Limiting Requests are rate-limited per API key based on your subscription plan. When a limit is exceeded the API returns `429 Too Many Requests` with a `Retry-After` header. ## Idempotency POST and PUT requests support idempotent replay via the optional `Idempotency-Key` header. Selected high-risk KPI and Health Metric write endpoints require this header to ensure safe retries without duplicate side-effects. ## Response Envelope Public v1 and v2 response contracts coexist during migration. Authenticated public endpoints use `PublicApiKeyMeta` semantics (`requestId`, `timestamp`) and anonymous public endpoints use `PublicAnonymousMeta` semantics. Anonymous library endpoints may add `PublicAnonymousLibraryMeta` tab-count metadata while authenticated public endpoints do not define a library tab-count metadata branch. ## Public Docs Visibility Policy Published public docs intentionally exclude anonymous Sessions and Library endpoints. Those v1 anonymous flows remain runtime-stable but are not listed in Mintlify-facing OpenAPI output. ## Migration Guidance For list endpoints, migrate in stages: keep v1 stable, adopt v2 offset mode first, then adopt v2 cursor mode where needed. Fallback expectation: clients may continue using v1 while v2 adoption is rolled out incrementally. ## Versioning & Deprecation Policy Breaking changes require a new major version (`/v2/`). Non-breaking additions ship in the current version. Deprecated endpoints include a `Sunset` HTTP header with the removal date. Minimum notice period: 6 months. contact: name: Agile Tools Developer Support url: https://teampoolz.mintlify.app email: dev-support@agile-tools.io version: 1.0.0 servers: - url: https://api.agile-tools.io description: Production - url: https://api.alpha.agile-tools.io description: Staging - url: https://free-trusty-kit.ngrok-free.app description: Local Development security: [] tags: - name: Address - name: Audit - name: Auth - name: Available scope - name: Billing Role - name: Billing Role Rate - name: Billing Role Rates - name: Billing Roles - name: Board - name: Budget - name: Budgets - name: Check In - name: Client - name: Client Project - name: Contact Info - name: Country - name: Demo Management - name: Goal - name: Goal Template - name: Goals - name: Group Notification Preferences - name: Groups description: Operations related to user groups - name: Health Metrics - name: Holiday Schemes - name: Hrosc - name: ISCO Groups - name: Integrations - name: Janitor System - name: Job Positions - name: KPIs - name: Key Result - name: Key Result Template - name: Key Results - name: Library Admin - name: Library Export - name: Library Import - name: Manager - name: Metric Period - name: Metric Template - name: Milestone - name: Nav Info - name: Newsletter - name: Notification Preferences - name: Observed Metrics - name: Org Account - name: Organizational Unit - name: Organizational Units - name: People - name: Person - name: Person Job Positions - name: Person Rate - name: Person Rates - name: Person Skills - name: Preferences - name: Public API Keys - name: Registration - name: SCM Repositories - name: Skills - name: Strategic Concept - name: Strategy - name: Stripe - name: Subscription - name: Sys Billing Role Rates - name: Sys Billing Roles - name: Sys Budgets - name: Sys Catalog - name: Sys Catalog Skill Groups - name: Sys Catalog Sync - name: Sys Check Ins - name: Sys Goals - name: Sys Job Positions - name: Sys Key Results - name: Sys Organizational Units - name: Sys Person - name: Sys Person Job Positions - name: Sys Person Rates - name: Sys Person Skills - name: Sys Public API Keys - name: Sys Skills - name: Sys Tags - name: Sys Teams - name: Sys Value Items - name: Sys Value Units - name: Tag - name: Tags - name: Team - name: Teams - name: Time zones - name: Timesheet - name: Timesheet Export - name: Timesheet Period Configuration - name: Timesheet Period Management - name: Timesheet Periods - name: Unit - name: Value Item - name: Value Item Settings - name: Value Items - name: Value Unit - name: Value Units - name: Webhooks - name: Workboards - name: Workflow - name: Workload Schemes - name: Worklog Approvals Configuration - name: Worklog Conflicts - name: Worklog Scheduler Configuration - name: Worklogs paths: /v1/public/people/{id}: patch: tags: - People summary: Update person description: >- Patch person mutable fields using JSON Merge Patch semantics. Omitted fields stay unchanged. Explicit null clears only managerId, externalId, and jobTitle. Explicit null for other fields is rejected with validation error. Resolve organizationalUnitId via GET /v1/public/organizational-units and managerId via GET /v1/public/people. operationId: updatePublicPerson parameters: - name: id in: path required: true schema: type: string requestBody: description: >- Merge-patch payload for mutable person fields. Omitted fields remain unchanged. Explicit null clears managerId, externalId, and jobTitle. Resolve organizationalUnitId via GET /v1/public/organizational-units and managerId via GET /v1/public/people. content: application/merge-patch+json: schema: $ref: '#/components/schemas/PublicPersonUpdateDto' examples: partial update: value: jobTitle: CTO clear manager and external id: value: {} required: true responses: '200': description: Person updated content: application/json: schema: $ref: '#/components/schemas/PublicPersonDto' examples: updated person: value: data: id: 318a0ed7-7d0f-45cc-b09e-a3c22cccb6ca firstName: Calvin Tyler lastName: Osborne email: calvin.tyler.osborne@de-mo.biz jobTitle: CTO organizationalUnitId: 2a5f8f2d-1ab1-4da0-a98f-6f6ff2ed1098 organizationalUnitName: Engineering basedIn: Ljubljana timeZoneName: Europe/Ljubljana deleted: false meta: requestId: f056699e-497d-41d9-a877-d7c862de6587 timestamp: '2026-04-03T12:08:00Z' '400': description: Invalid merge-patch payload '404': description: Person not found '409': description: Email or externalId already exists security: - apiKey: [] components: schemas: PublicPersonUpdateDto: type: object properties: firstName: type: string nullable: true lastName: type: string nullable: true email: type: string nullable: true externalId: type: string nullable: true jobTitle: type: string nullable: true organizationalUnitId: description: Organizational unit id in the authenticated organization. type: string example: a5ec8a9e-b6a9-4230-9ce9-8db4bb40f6ff nullable: true managerId: description: Manager id in the authenticated organization. type: string example: 2f6db7d4-6e6c-4d4f-90f2-cbaac8441f7b nullable: true basedIn: type: string nullable: true timeZoneName: type: string nullable: true PublicPersonDto: type: object properties: id: type: string firstName: type: string lastName: type: string email: type: string externalId: type: string jobTitle: type: string organizationalUnitId: type: string organizationalUnitName: type: string managerId: type: string managerName: type: string joined: format: date-time type: string basedIn: type: string timeZoneName: type: string groups: type: array items: $ref: '#/components/schemas/PublicNamedReferenceDto' teams: type: array items: $ref: '#/components/schemas/PublicNamedReferenceDto' workloadScheme: $ref: '#/components/schemas/PublicNamedReferenceDto' holidayScheme: $ref: '#/components/schemas/PublicNamedReferenceDto' deleted: type: boolean PublicNamedReferenceDto: type: object properties: id: type: string name: type: string securitySchemes: apiKey: type: apiKey description: >- Owner-typed API key (`ORGANIZATION`, `PERSON`, `VALUE_UNIT`). Manage org-scoped lifecycle with `/v1/public-api-keys`; cross-org governance is restricted to `/v1/sys/public-api-keys`. name: X-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.