Organization

An Organization is a container for your workspaces. We are going to talk about Workspaces in the next page. The Enterprise plan allows you to easily to manage large teams from multiple workspaces under one organization. This way, you can group your users and select which workspaces they have access to.

Create an Organization

caution

You can create multiple organizations. Each organization has its own plan. You cannot share your Plan between multiple organizations.

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -d '{"name":"Your Organization","workspace_name":"Your Workspace"}' \
  -X POST https://api.track.toggl.com/api/v9/organizations

When you create a new organization, you need to specify the organization name and the default workspace name as required in the Toggl Track web app. The user who has created the organization is the default Owner.

Organization ownership can be changed from the Organization Admin Page.

Organization Data

In order to retrieve your organizations data, you can do the following request:

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -X GET https://api.track.toggl.com/api/v9/me/organizations

The response will contain the following data:

[
  {
    "admin": true,
    "at": "2021-01-30T09:08:04+00:00",
    "created_at": "2021-01-30T09:08:04+00:00",
    "id": 1,
    "is_multi_workspace": false,
    "name": "Your Organization",
    "owner": true,
    "pricing_plan_id": 1,
    "server_deleted_at": ""
  },
  ...
]

Retrieving data for a specific organization:

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -X GET https://api.track.toggl.com/api/v9/organizations/1

Response:

{
    "admin": false,
    "at": "2021-03-23T18:11:05.130253Z",
    "created_at": "2021-11-01T08:00:00.123458Z",
    "id": 1,
    "is_chargify": false,
    "is_multi_workspace_enabled": true,
    "max_workspaces": 20,
    "name": "Your Organization",
    "owner": false,
    "pricing_plan_id": 103,
    "server_deleted_at": null,
    "suspended_at": null,
    "trial_info": {
        "last_pricing_plan_id": 100,
        "next_payment_date": "2022-03-23T00:00:00Z",
        "trial": false,
        "trial_available": false,
        "trial_end_date": null
    },
    "user_count": 103
}

Add a user to the organization

First, let's create a new user:

curl -u <email>:<password> \
     -H 'content-type: application/json' \
     --data-raw '{"created_with": "script", "email": "test-user@test.com", "password": "S3cr3t12345.", "tos_accepted": true, "country_id": 102, "workspace": { "initial_pricing_plan": 0 }, "timezone": "Etc/UTC"}' \
     -X POST 'https://api.track.toggl.com/api/v9/signup'

Response:

{"id":2,"api_token":"d82b3fa96f34ebe17f887c6a3c82540b","email":"test-user@test.com","fullname":"Test-User","timezone":"Etc/UTC","default_workspace_id":42,"beginning_of_week":1,"image_url":"https://assets.track.toggl.com/images/profile.png","created_at":"2022-03-30T12:56:51.545866Z","updated_at":"2022-03-30T12:56:51.545866Z","openid_email":null,"openid_enabled":false,"country_id":102,"at":"2022-03-30T12:56:51.619396Z"}

Let's invite the newly created user to our organization:

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  --data-raw '{"emails": ["test-user@test.com"], "workspaces": [{"workspace_id": 2, "admin": false}]}' \
  -X POST https://api.track.toggl.com/api/v9/organizations/1/invitations

Response:

{"data":[{"invitation_id":42,"sender_id":1,"recipient_id":2,"organization_id":1,"email":"invited-user-email@example.com","invite_url":"https://toggl.com/track/#signup/abc4341324abcdef3434234abbbdef1a"}]}

The invited user should see the invitation among his notifications: (Use the credentials of the newly invited user, not the admin who sent the invitation!)

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -X GET https://api.track.toggl.com/api/v9/organizations/me/notifications

Response:

[
    {
        "actions": {
            "decline": {
                "code": "5ae7b4eb146b073457b0b0f1c1fb7ddc",
                "type": "reject"
            },
            "default": "decline",
            "join": {
                "code": "5ae7b4eb146b073457b0b0f1c1fb7ddc",
                "type": "accept"
            }
        },
        "class": 0,
        "content": {
            "default_message": "Admin invited you to join Your Organization<br /> <button name=\"join\">Join</button> or <button name=\"decline\">Decline</button>",
            "id": "Notification.invitation.content",
            "values": {
                "userName": "Admin",
                "workspaceName": "Your Workspace"
            }
        },
        "created_at": "2022-03-30T13:02:40.714139Z",
        "id": 1,
        "notification_type": "invitation",
        "organization_id": null,
        "title": {
            "default_message": "New invitation",
            "id": "Notification.invitation.title",
            "values": null
        },
        "user_id": 2,
        "workspace_id": null
    }
]

The invited user accepts the invitation: (use his credentials, not the admin's!)

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -X POST "https://api.track.toggl.com/api/v9/organizations/invitations/5ae7b4eb146b073457b0b0f1c1fb7ddc/accept"

The response body is empty, the status 200 OK means that the operation was successful.

Now the invited user is among the users of the organization (works with the credentials of the admin, not those of the user!):

curl -u <email>:<password> \
  -H "Content-Type: application/json" \
  -X GET https://api.track.toggl.com/api/v9/organizations/1/users

Response

[
    {
        "admin": false,
        "avatar_url": "",
        "can_edit_email": false,
        "email": "test_user@test.com",
        "groups": [
        ],
        "id": 5115086,
        "inactive": false,
        "invitation_code": null,
        "joined": true,
        "name": "Test User",
        "owner": false,
        "user_id": 2,
        "workspaces": [
            {
                "admin": false,
                "name": "Your Workspace",
                "workspace_id": 2
            }
        ]
    },
...
]