First Steps with the shyftplan API

Our API gives you access to most commands that you can invoke on our website. You can embed those commands in your own scripts - and automate things you do often.
Check out some of the endpoints (displayed in alphabetical order) in the navigation menu to the left. You will find out:

📘

Get started!

To use the shyftplan API and its many methods and endpoints, you always need credentials. The kind of credentials vary slightly - but most often

• your company id,
• your API user's email address and
• your API user's token is required.

So, first things first. Let's get your company id!

How to find the company id

Head over to your account in shyftplan. You'll land on your dashboard, and this is a fast and easy way to find your company id - it's in the URL:

In this case, the company id happens to be 51594.

📘

What was it again...?

If you plan to do a lot of work with our API, we suggest writing down your company id somewhere handy. You'll need it again and again. In fact, even when an API endpoint does not require you to pass this id, it doesn't hurt to provide it anyway.

How to find the email address

Find your email address by logging in to your shyftplan account and clicking on your user name (top right) and then choosing "Profile" from the drop-down menu:

You will need this email address, like the company id and the token (see next chapter), over and over.
Our recommendation is to store email address and token in separate places, but in easy reach. You may want to use a password manager for that.

📘

Best Practice: Create a second user for API calls

Only registered shyftplan users can use the API. You can use "your own user": the identity with which you log in to your account.

Or create a "special user" just for the API. Most of our customers prefer this second way after they have completed the initial testing. By using an additional user account, you can share its password with developers and admins and don't compromise your (main) shyftplan user account.

Whatever user account you take for our API will have the same rights and face the same restrictions there as it does on the web app: If you are allowed to accept employees' absence applications on shyftplan.com, then you can do the same via the API. If you can't usually see other employees but only your own shifts, then the API won't help you, either.

How to find the token

The token is a string that functions as an API password. The API will respond with an error unless you provide a token that is valid in a shyftplan company account for the API user's email address.
We want to show you the two ways to get a token for your email address. Both ways work only ONE TIME: You send out a request for a new token and receive it in the answer. It is not possible (for anybody) to read the token again at a later time. But you can always create (an unlimited number of) additional tokens. All your tokens are invalid at the moment you change your user's login password, or when you've deleted those tokens.

Token creation via the GUI

Head over to your Profile once more by clicking on your user name in the top right in your shyftplan account (choose "Profile" from the drop-down menu).

• Now scroll down to the end of the page. You'll see the caption "API Tokens". Click on "+" to the right of the caption. Give your token any name (e.g. the current date, so that in the list of tokens you can see their age at a glance). The name has no relevance for the system, and you don't have to remember it.
• Click on "Send"

• In the next dialog, find your token, printed in bold, and copy that to some safe place. The dot at the end is not part of the token. You will only see the token this one time! After that, it's safely stored, but you cannot retrieve it anymore.
• Check the checkbox and click on "Confirm", and you're done.
• If you forget the token, you can always go back to this Profile page and then create a fresh token. While you are at it, we recommend you delete all listed tokens that you no longer use.

Token creation via the API

Use this endpoint.
This is the only endpoint that does not require a token but your login credentials instead. Enter your user name and password, and click on Try It! on the right.
You will then get the new token in the answer below.

📘

Undeletable token?

When you choose this second way to create a token, it will not appear in the list of tokens on your Profile page. How can you delete it, then, in case you don't need it anymore?
There is no method in the API for that, but you can log in to your shyftplan account and change your password on your Profile page. This will automatically delete all your API-created tokens.

What now?

With these three pieces of information you are ready to try out your first endpoints. You can, for example, use this method to get a list (in JSON format) of all the absences that exist for employees in your account. Try It!

📘

Need help?

If you have any questions or require further information, do not hesitate to contact us directly.