> 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/advisor-management-resource.md).

# Advisor Management Resource

## Replace the companies an advisor advises

> The given set becomes exactly the companies the person advises; companies left out go back to ADMIN. An empty set revokes the advisor.

```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":{"AdvisorCompaniesRequest":{"type":"object","description":"Exact set of companies the advisor must advise","properties":{"companyIds":{"type":"array","description":"Companies to advise. Companies left out lose the ADVISOR role; an empty set revokes the advisor.","items":{"type":"string"},"uniqueItems":true}},"required":["companyIds"]},"Advisor":{"type":"object","description":"Person acting as advisor and the companies they advise","properties":{"id":{"type":"string","description":"Person id"},"name":{"type":"string"},"email":{"type":"string"},"pureAdvisor":{"type":"boolean","description":"Pure advisors advise every company and cannot be edited from the dashboard"},"companies":{"type":"array","description":"Companies where the person holds the ADVISOR role, sorted by name. Empty for a pure advisor.","items":{"$ref":"#/components/schemas/Company"}}}},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/api/v1/company/advisor/advisors/{personId}/companies":{"put":{"tags":["advisor-management-resource"],"summary":"Replace the companies an advisor advises","description":"The given set becomes exactly the companies the person advises; companies left out go back to ADMIN. An empty set revokes the advisor.","operationId":"setAdvisorCompanies","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorCompaniesRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Advisor"}}}}}}}}}
```

## List advisors

> Pure advisors and every person with the ADVISOR role on at least one company, sorted by e-mail.

```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":{"Advisor":{"type":"object","description":"Person acting as advisor and the companies they advise","properties":{"id":{"type":"string","description":"Person id"},"name":{"type":"string"},"email":{"type":"string"},"pureAdvisor":{"type":"boolean","description":"Pure advisors advise every company and cannot be edited from the dashboard"},"companies":{"type":"array","description":"Companies where the person holds the ADVISOR role, sorted by name. Empty for a pure advisor.","items":{"$ref":"#/components/schemas/Company"}}}},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/api/v1/company/advisor/advisors":{"get":{"tags":["advisor-management-resource"],"summary":"List advisors","description":"Pure advisors and every person with the ADVISOR role on at least one company, sorted by e-mail.","operationId":"listAdvisors","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Advisor"}}}}}}}}}}
```

## Promote an admin to advisor of some companies

> Turns the person's ADMIN role on the given companies into ADVISOR, keeping the ones already advised. Fails with USER\_DOSNT\_EXISTS when no person has that e-mail, ADVISOR\_REQUIRES\_ADMIN when the person is not admin of one of the companies, INVALID\_PERMISSIONS\_INFO for a missing or unknown company, and PURE\_ADVISOR\_NOT\_MANAGEABLE for a pure advisor.

```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":{"AdvisorGrantRequest":{"type":"object","description":"Existing person to make advisor of the given companies","properties":{"email":{"type":"string","description":"E-mail of a person that already exists in Happyforce"},"companyIds":{"type":"array","description":"Companies to advise, added to the ones the person already advises","items":{"type":"string"},"uniqueItems":true}},"required":["companyIds","email"]},"Advisor":{"type":"object","description":"Person acting as advisor and the companies they advise","properties":{"id":{"type":"string","description":"Person id"},"name":{"type":"string"},"email":{"type":"string"},"pureAdvisor":{"type":"boolean","description":"Pure advisors advise every company and cannot be edited from the dashboard"},"companies":{"type":"array","description":"Companies where the person holds the ADVISOR role, sorted by name. Empty for a pure advisor.","items":{"$ref":"#/components/schemas/Company"}}}},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/api/v1/company/advisor/advisors":{"post":{"tags":["advisor-management-resource"],"summary":"Promote an admin to advisor of some companies","description":"Turns the person's ADMIN role on the given companies into ADVISOR, keeping the ones already advised. Fails with USER_DOSNT_EXISTS when no person has that e-mail, ADVISOR_REQUIRES_ADMIN when the person is not admin of one of the companies, INVALID_PERMISSIONS_INFO for a missing or unknown company, and PURE_ADVISOR_NOT_MANAGEABLE for a pure advisor.","operationId":"grantAdvisor","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvisorGrantRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/Advisor"}}}}}}}}}
```

## Revoke an advisor

> Turns every ADVISOR permission of the person back into ADMIN. Their employee profile and other roles are kept.

```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"}}},"paths":{"/api/v1/company/advisor/advisors/{personId}":{"delete":{"tags":["advisor-management-resource"],"summary":"Revoke an advisor","description":"Turns every ADVISOR permission of the person back into ADMIN. Their employee profile and other roles are kept.","operationId":"revokeAdvisor","parameters":[{"name":"personId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}
```
