An organization serves as a container for your workspaces. We will discuss workspaces in a separate topic. The Enterprise plan allows you to efficiently manage large teams across multiple workspaces within a single organization. This enables you to group your users and determine which workspaces they can access.
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 } ] },...]