Read the people directory from a script

Keep another system in step with your organization: read its members, their managers and departments, and its teams.

In short

Two read-only addresses answer the directory of one organization: its accepted members and the teams you may see. A script reads them with an access token. Nothing here changes the organization.

A token that may also change Organizations keeps the team structure in step: it creates, renames, moves and deletes teams, changes who is in a team and names its lead and deputy. Members, invitations, roles, billing, security and ownership stay for a person at their screen.

Before you start

Make an access token in Settings › Access tokens and let it read Organizations.
The token acts as you. You need "See members" for the members and "See teams" for the teams.
Send the organization's id in the X-Organization-Id header. Without it, the token reads your Personal Workspace, which has no directory.

Read the members

Email addresses The directory never sends email addresses. Match people by userId.

Read a large organization page by page

Ask with take=500 or less, and skip=0.
Members come in a fixed order: by name, then by id.
Ask again with skip raised by take, until a page holds fewer people than take.
Leave both out to get everyone at once. Use pages when the organization is large.

Read the teams

Each team has its id, parentTeamId, name, description, leadUserId, deputyUserId and memberIds. A top-level team has no parentTeamId. Build the tree from parentTeamId. A team hidden from you is left out, and so is everything about it.

If something goes wrong

400: skip is below 0, or take is not between 1 and 500.
403: the token may not read Organizations, or you lack "See members" or "See teams".
404: the organization in X-Organization-Id is not one you are a member of.

/help/settings/access-tokens
/help/organizations/manager-line-and-org-chart
/help/organizations/teams-and-hierarchy