Skip to content
This repository was archived by the owner on Feb 3, 2021. It is now read-only.

roles.md

Latest commit

 

History

History
109 lines (72 loc) · 2.79 KB

roles.md

File metadata and controls

109 lines (72 loc) · 2.79 KB
Raw

Roles

Retrieving Roles (GET)

Get all Roles for Organization

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/roles

Get a specific Role

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/roles/$ROLE_ID

Filtering by Person

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/roles?person_id=$PERSON_ID

OR

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/people/$PERSON_ID/roles

Filtering by Circle

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/roles?circle_id=$CIRCLE_ID

OR

curl -H "X-Auth-Token: $API_KEY" https://api.glassfrog.com/api/v3/circles/$CIRCLE_ID/roles

Response Format

{
  "linked": {
    "circles": [
      {
        "id": 582240928,
        "name": "Operations",
        "short_name": "Ops",
        "strategy": "Emphasize \"Documenting & Aligning to Standards\", even over \"Developing & Co-Creating Novelty\"",
        "links": {
        }
      }
    ],
    "people": [
      {
        "id": 811765527,
        "name": "Carlos Aldrich",
        "email": "carlos@example.com",
        "external_id": null
      }
    ]
  },
  "roles": [
    {
      "id": 83866836,
      "name": "Fulfillment Role",
      "purpose": null,
      "links": {
        "domains": [],
        "accountabilities": [],
        "circle": 582240928,
        "people": [
          811765527
        ]
      }
    }
  ]
}

Attribute Notes

  • elected_until: elected roles will include elected_until attribute, which returns the end date for current term

Updating Role Assignments (PATCH/PUT)

With the exception of Lead Link roles, role assignment is additive and will add new role-fillers. Assigning Lead Links is special case, see below for more details.

Adding a Role Assignment

curl -H "X-Auth-Token: $API_KEY" -X PATCH -d '[{"op":"add","path":"/roles/0/links/people/$PERSON_ID"}]' https://api.glassfrog.com/api/v3/roles/$ROLE_ID

Removing Role Assignment

curl -H "X-Auth-Token: $API_KEY" -X PATCH -d '[{"op":"remove","path":"/roles/0/links/people/$PERSON_ID"}]' https://api.glassfrog.com/api/v3/roles/$ROLE_ID

Emails Sent

Assigning roles via the API will send email notifications to added and removed role-fillers.

Assigning Lead Links

To assign to the Lead Link of a circle, you must assign to the corresponding role in the super-circle; you can't assign directly to the Lead Link role of a circle. Additionally, this role is always single filled, and assigning it will replace the current role-filler rather than adding a new role-filler. In the case of a successful replacement, the API will return 200 and the role, otherwise if there is no previous role-filler that is replaced, it will return 204.