Getting started with PlanMill API
The easiest way to start exploring and using PlanMill API is using a free API tool called Postman, although you can use any client.
You can use of course any tools you would like, but this guide is written using Postman as example.
Get Postman (optional, but recommended)
We recommend free Postman extension to Chrome or Mac for easy access to trying out our API and to generate the client code in your favorite programming language.
Chrome and Mac apps available: https://www.getpostman.com/
Get our API docs on your computer
We are using RAML standard four our API design and documentation, so you can directly use our docs for your API tools.
Clone this repository to your computer (or just download a .zip file)
Import the docs to Postman or other API client
Most tools provide ways to use the RAML documentation directly, so does Postman. For other tooling, check http://raml.org/projects/projects
There are a few files in the repository which don't belong to the actual docs, so only use .raml, .schema and .sample for this step.
This will get all of our API calls as an easy collection that you can start using immediately
What url do I make my API calls to?
The url to the API is for Cloud customers
If you have imported the API as a collection to Postman in the previous step, Postman has automatically converted the urls to use URI (path) parameters. So the url in Postman looks like this with ":instance" as the path parameter:
Just click "Params" to edit the parameters and set the instance name to your own.
If you are not yet a PlanMill customer, go to https://www.planmill.com/plans-pricing/ , pick a suitable product package and register for Free Trial using your business email account.
If you want to test only the api. go to Request access to OpenAPI instance
Register a client for your API calls
We use Oauth2 / OpenID Connect in PlanMill for authentication so you need to register a client in PlanMill to get API access.
Prepare to make your first API call
We have selected you the first API call you should make:
This API call is very safe as it only gets you your own user information and doesn't make any changes nor requires any parameters.
Select this GET /me -endpoint from the Postman Collections -tab under PlanMill -collection. Remember to set the instance -parameter to your instance.
Setup authentication in Postman
Prerequests : Create new role for API access and create new user and assign that role. Add access to new role that you created to use api. HRM -> Users -> View user api key (Employeedirectory.Users view api key) If above access right is not added, you will get "401 Unauthorized" when you perform registration.
Step 1 (Register OAuth 2.0 for Postman) :
- Provide "Allowed redirect URIs" as https://www.getpostman.com/oauth2/callback - To automatically refresh access tokens select "Refresh secret, if Client ID exists" as "Yes" otherwise leave it as default "No". - Click on Register and collect the "Current registrations" section's newly generated ClientId and ClientSecret which we are going to use it in Postman to authenticate planmill api.
Step 2 (Postman Access token setup)
In Postman, under the api call url, find the Authorization -tab. Select "OAuth 2.0" from the "Type" list. For further information see Postman guide section Oauth2.
Click "Get new access token"
Enter authentication details as below
- Authorization url: https://online.planmill.com/:instance/api/oauth2/authorize
- Token url: https://online.planmill.com/:instance/api/oauth2/token
- Client id: copy from the client registration page (Step 1)
- Client secret: copy from the client registration page (Step 1)
You don't need to set scope (if empty it will default to the only allowed scope "openid" since we are using OpenID Connect).
Leave Grant type as "Client Credentials".
- Click "Request token", a login window opens
- Log in to your PlanMill instance with the authorized credentials
- After successful login, the login window closes and you have a new access token
- Select the token you just created, select "Add to Header" and click "Use token". Postman will add the token to the request headers as "Bearer"
- Done! You can make as many calls you would like in the next 360 seconds (Or as per the settings in your application) while the access token is valid. After that repeat steps 2-6 to get new token (Postman will remember your settings and you don't need to register another client).
In case you use some other client application or need to get the access token programmatically, here are the example requests:
Make API calls using your favorite programming language
Use the "Generate code" in Postman for generating the API request in the programming language of your choice like Java, PHP, Node.js etc.
Implementation example in Java language is available here: https://github.com/planmill/api-data-helper