> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/user-focus-migration-resource.md).

# User Focus Migration Resource

## Adjust one row's focus

> Records the company's own focus for this person, overriding the proposal. Rejected with 409 DRAFT\_CONFIRMED once the company confirmed, with 412 COMPANY\_ALREADY\_ACTIVATED once Happyforce applied it, or if the row is STALE (the person is no longer MANAGER/ADMIN).

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"FocusMigrationAdjustRequest":{"type":"object","description":"The company's own pick for one row","properties":{"focus":{"$ref":"#/components/schemas/ManagementFocus","description":"The focus the company picks for this person, overriding the proposal"}},"required":["focus"]},"ManagementFocus":{"type":"string","description":"The focus/interest a user has when consuming their report","enum":["TEAM_LEAD","MANAGER_OF_MANAGERS","EXECUTIVE","PEOPLE_ADVISOR","PEOPLE_EXECUTIVE","ACCOUNT_ADMIN","GENERIC"]},"FocusMigrationRow":{"type":"object","properties":{"userId":{"type":"string","description":"Person id (24-char hex)"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ADVISOR","ADMIN","RESPONSIBLE","PUBLIC","MANAGER","EMPLOYEE"]},"areas":{"type":"array","description":"The hierarchy nodes this person currently manages, for context.","items":{"$ref":"#/components/schemas/FocusMigrationAreaRef"}},"declaredFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The focus already declared in the person's permissions when this row was last (re)generated; null when none was declared."},"structuralSuggestion":{"$ref":"#/components/schemas/ManagementFocus","description":"What the structural heuristic reads off the org chart, independent of what is declared; null when the person covers no area."},"confidence":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"reasons":{"type":"array","items":{"type":"string","enum":["ADMIN_NOT_INFERABLE","NO_AREAS","COVERS_TOP","MANAGERS_BELOW","NO_MANAGERS_BELOW","SUBAREAS_WITHOUT_MANAGER","CO_EXECUTIVES_SAME_NODE"]}},"managersBelow":{"type":"integer","format":"int32","description":"Count of other MANAGERs reporting into this person; meaningful only alongside the MANAGERS_BELOW reason."},"proposedFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"declaredFocus when present, otherwise the AI review's correction or structuralSuggestion. Never null: every row has a proposal."},"proposalSource":{"type":"string","description":"Where proposedFocus came from. AI_REVIEW: an AI review corrected the structural suggestion; aiReason, aiEvidence and aiConfidence say why. Never set over a declared or adjusted focus.","enum":["DECLARED","LEGACY_ROLE","STRUCTURE","ADMIN_DEFAULT","AI_REVIEW","NONE"]},"aiReason":{"type":"string","description":"One sentence from the AI review saying why it corrected the structural suggestion. Non-null only when proposalSource is AI_REVIEW. English; shown as is."},"aiEvidence":{"type":"string","description":"The datum the AI review rests its correction on (a team name, who holds the same nodes...). Non-null only when proposalSource is AI_REVIEW."},"aiConfidence":{"type":"string","description":"How much the AI review trusts its own correction. Non-null only when proposalSource is AI_REVIEW; independent of confidence, which stays the structural rule's.","enum":["LOW","MEDIUM","HIGH"]},"needsHumanReview":{"type":"boolean","description":"True when a person should look at this row before activating: the person declares no area (reasons has NO_AREAS) or several EXECUTIVEs hold exactly the same nodes (reasons has CO_EXECUTIVES_SAME_NODE). The row still carries a proposed focus; the mark never blocks activation."},"adjustedFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The company's own pick, overriding proposedFocus; null until adjusted."},"finalFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The focus that will be (or was) written to permissions: adjustedFocus when present, otherwise proposedFocus."},"status":{"type":"string","enum":["PROPOSED","NEEDS_DECISION","ADJUSTED","APPLIED","STALE"]}}},"FocusMigrationAreaRef":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/api/v1/company/people/focus-migration/{userId}":{"put":{"tags":["user-focus-migration-resource"],"summary":"Adjust one row's focus","description":"Records the company's own focus for this person, overriding the proposal. Rejected with 409 DRAFT_CONFIRMED once the company confirmed, with 412 COMPANY_ALREADY_ACTIVATED once Happyforce applied it, or if the row is STALE (the person is no longer MANAGER/ADMIN).","operationId":"adjust","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FocusMigrationAdjustRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FocusMigrationRow"}}}}}}}}}
```

## Confirm the draft

> Records that the company reviewed the draft and it is correct. Writes nothing to permissions: Happyforce applies it afterwards. Once confirmed the rows can no longer be adjusted until Happyforce reopens the draft. Idempotent; refused only when there is no draft at all (see reason).

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"FocusMigrationConfirmResult":{"type":"object","description":"Outcome of the company confirming its focos y roles draft","properties":{"confirmed":{"type":"boolean","description":"True when the draft is confirmed (now, or already was)"},"alreadyConfirmed":{"type":"boolean","description":"True when the draft had already been confirmed; confirmed is also true in that case, and confirmedAt is the original moment"},"confirmedAt":{"type":"string","format":"date-time","description":"When the company confirmed; null when refused"},"reason":{"type":"string","description":"Why confirming was refused: NO_DRAFTS (nothing to confirm). Null when confirmed is true.","enum":["NO_DRAFTS"]}}}}},"paths":{"/api/v1/company/people/focus-migration/confirm":{"post":{"tags":["user-focus-migration-resource"],"summary":"Confirm the draft","description":"Records that the company reviewed the draft and it is correct. Writes nothing to permissions: Happyforce applies it afterwards. Once confirmed the rows can no longer be adjusted until Happyforce reopens the draft. Idempotent; refused only when there is no draft at all (see reason).","operationId":"confirm","responses":{"200":{"description":"Confirmed (or already was)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FocusMigrationConfirmResult"}}}},"409":{"description":"Refused; see reason (NO_DRAFTS)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FocusMigrationConfirmResult"}}}}}}}}}
```

## The account's focos y roles draft

> Every current MANAGER/ADMIN's row — declared focus, structural suggestion, the resulting proposal, and the company's own adjustment if any — plus totals by status and when the company confirmed and when Happyforce applied it.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"FocusMigration":{"type":"object","description":"Draft ManagementFocus proposal for every MANAGER/ADMIN of the account","properties":{"activatedAt":{"type":"string","format":"date-time","description":"When Happyforce applied focos y roles to permissions. Null while still in draft; the rows are then read-only."},"draftConfirmedAt":{"type":"string","format":"date-time","description":"When the company confirmed the draft is correct. Null while unconfirmed (or after Happyforce reopened it). While set, rows can no longer be adjusted (PUT answers 409 DRAFT_CONFIRMED)."},"confirmedBy":{"type":"string","description":"Person id (24-char hex) of the ADMIN who confirmed; null while unconfirmed."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/FocusMigrationRow"}},"totals":{"$ref":"#/components/schemas/FocusMigrationTotals"}}},"FocusMigrationRow":{"type":"object","properties":{"userId":{"type":"string","description":"Person id (24-char hex)"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ADVISOR","ADMIN","RESPONSIBLE","PUBLIC","MANAGER","EMPLOYEE"]},"areas":{"type":"array","description":"The hierarchy nodes this person currently manages, for context.","items":{"$ref":"#/components/schemas/FocusMigrationAreaRef"}},"declaredFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The focus already declared in the person's permissions when this row was last (re)generated; null when none was declared."},"structuralSuggestion":{"$ref":"#/components/schemas/ManagementFocus","description":"What the structural heuristic reads off the org chart, independent of what is declared; null when the person covers no area."},"confidence":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"reasons":{"type":"array","items":{"type":"string","enum":["ADMIN_NOT_INFERABLE","NO_AREAS","COVERS_TOP","MANAGERS_BELOW","NO_MANAGERS_BELOW","SUBAREAS_WITHOUT_MANAGER","CO_EXECUTIVES_SAME_NODE"]}},"managersBelow":{"type":"integer","format":"int32","description":"Count of other MANAGERs reporting into this person; meaningful only alongside the MANAGERS_BELOW reason."},"proposedFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"declaredFocus when present, otherwise the AI review's correction or structuralSuggestion. Never null: every row has a proposal."},"proposalSource":{"type":"string","description":"Where proposedFocus came from. AI_REVIEW: an AI review corrected the structural suggestion; aiReason, aiEvidence and aiConfidence say why. Never set over a declared or adjusted focus.","enum":["DECLARED","LEGACY_ROLE","STRUCTURE","ADMIN_DEFAULT","AI_REVIEW","NONE"]},"aiReason":{"type":"string","description":"One sentence from the AI review saying why it corrected the structural suggestion. Non-null only when proposalSource is AI_REVIEW. English; shown as is."},"aiEvidence":{"type":"string","description":"The datum the AI review rests its correction on (a team name, who holds the same nodes...). Non-null only when proposalSource is AI_REVIEW."},"aiConfidence":{"type":"string","description":"How much the AI review trusts its own correction. Non-null only when proposalSource is AI_REVIEW; independent of confidence, which stays the structural rule's.","enum":["LOW","MEDIUM","HIGH"]},"needsHumanReview":{"type":"boolean","description":"True when a person should look at this row before activating: the person declares no area (reasons has NO_AREAS) or several EXECUTIVEs hold exactly the same nodes (reasons has CO_EXECUTIVES_SAME_NODE). The row still carries a proposed focus; the mark never blocks activation."},"adjustedFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The company's own pick, overriding proposedFocus; null until adjusted."},"finalFocus":{"$ref":"#/components/schemas/ManagementFocus","description":"The focus that will be (or was) written to permissions: adjustedFocus when present, otherwise proposedFocus."},"status":{"type":"string","enum":["PROPOSED","NEEDS_DECISION","ADJUSTED","APPLIED","STALE"]}}},"FocusMigrationAreaRef":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"ManagementFocus":{"type":"string","description":"The focus/interest a user has when consuming their report","enum":["TEAM_LEAD","MANAGER_OF_MANAGERS","EXECUTIVE","PEOPLE_ADVISOR","PEOPLE_EXECUTIVE","ACCOUNT_ADMIN","GENERIC"]},"FocusMigrationTotals":{"type":"object","properties":{"proposed":{"type":"integer","format":"int32"},"needsReview":{"type":"integer","format":"int32","description":"Rows marked needsHumanReview (counted in their own status too)"},"adjusted":{"type":"integer","format":"int32"},"applied":{"type":"integer","format":"int32"},"stale":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/company/people/focus-migration":{"get":{"tags":["user-focus-migration-resource"],"summary":"The account's focos y roles draft","description":"Every current MANAGER/ADMIN's row — declared focus, structural suggestion, the resulting proposal, and the company's own adjustment if any — plus totals by status and when the company confirmed and when Happyforce applied it.","operationId":"get","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FocusMigration"}}}}}}}}}
```
