Skip to main content

 

  • arrow icon

 

Language Selector

  1. Other Languages

    (machine translation)

Planview Customer Success Center

Planview Admin API

  1. Last updated
  2. Save as PDF

Overview

The Planview Admin API provides programmatic access for querying and managing Planview Admin resources. It currently supports the following:

  • Searching and managing users
  • Retrieving user audit history
  • Retrieving customer audit history
  • Retrieving assigned products
  • Retrieving users provisioned to products

           

NOTE

This page provides a basic overview of the API's features and limits. To read the API endpoint documentation please see the following page:

           

Authentication

All API endpoints documented here require a valid JWT bearer token in the Authorization header.

Client Credentials

A client credentials flow can be used with client credentials created inside of Planview Admin’s settings tab. To obtain a JWT bearer token using client credentials, make a request with the following parameters:

    URL:              /io/v1/oauth2/token
    Method:           POST
    Headers:
      Content-Type:   application/x-www-form-urlencoded
      Authorization:  Basic <Base64 encoded client_id:client_secret>
    Body (form-data):
      grant_type=client_credentials

The response will contain an id_token field which is the JWT bearer token to be used in subsequent API requests. Each of those requests must include the following header:

    Authorization:  Bearer <id_token>

Rate Limiting

Rate limiting is implemented to minimize excessive API usage. This allows access to our API while still protecting the integrity of our systems.

The API rate limit is per customer. Hitting the API rate limit will not prevent a user from using the web interface to access Planview Admin.

Working with Rate Limits

We maintain the ability to adjust the rates as needed for the health of the system. So instead of planning for a specific rate of requests, your code should inspect the X-Rate-Limit-Remaining HTTP header included in success responses so you know when you are approaching the limit. This header indicates the number of points remaining in this time window.

When the limit is exceeded, a 429 Too Many Requests response will be returned. At that point, your code should back off and wait the number of seconds indicated in the Retry-After header before making further requests.

Paging

Some endpoints may return large result sets. To help manage response sizes, these endpoints support paging through the results using the following query parameters and keys in the JSON response.

Paging Query Parameters

  • startIndex is an optional 1-based index indicating the requested starting point of the results to return. The default is 1.
  • count is an optional parameter indicating the number of items to return per page. Each endpoint specifies its default and maximum values.

Paging Response Keys

  • startIndex indicates the 1-based index of the first item included in the current response page.
  • itemsPerPage indicates the maximum number of items included in the current response.
  • Resources is an array containing the items in the current response page.

Working with Paged Responses

Upon receiving the first paged response, your code should compare the length of the Resources array with the itemsPerPage value. If an empty array is returned or its length is less than itemsPerPage, there are no more results to retrieve. If there are more items to retrieve, make the request again with the startIndex query parameter set to the sum of the response's startIndex and itemsPerPage.

For example, if the first request is:

    GET /public/v1/user?startIndex=1&count=50

then the second request would be:

    GET /public/v1/user?startIndex=51&count=50