Publish Org Chart

With Org Chart information, the Productiv platform enables visibility into user activity across the customer’s app portfolio. This allows us to segment activity and display insights for different teams, locations and managers. We also allow the customer to create custom segments.

These API can be used to push a snapshot of org chart data to Productiv from one or more existing systems. The user can also get the latest snapshot of their org chart data using the APIs. Productiv treats the latest snapshot of the data as the current org chart for the organization.

Prerequisites

  • In order to query this API, you would also need to send an access_token as part of the Authorization header. Visit the Authorization section to see the steps for generating an access token.

Publishing Org Chart Data

In order to upload the current snapshot of the org chart, follow the steps:

  1. Request for a resource ID by doing a POST request to Productiv. A resource ID acts as a uniform resource Identifier which helps us to map different set of users list (sent to us through multiple PUT requests) for the same snapshot of org chart to a single identifier.

  2. Using the resource ID, send org chart data using follow-up PUT requests.

Requesting Resource Id Endpoint

POST https://public-api.productiv.com/services/push/v1/customer/org-chart

Include the following headers along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token
Required Scope https://api.productiv.com/connector.write

Request Body Schema

orgChartName provides a mapping resource for the customer which would be associated with a resource Id. Customer can request for a new resource ID by doing a POST with a new orgChartName. orgChartName can be any random string that you can choose to associate your snapshot with (eg: date of the org chart data, a universally unique identifier etc. )

{
    "orgChartName": String
}

Org Chart Request Object

Property Datatype Description Optional
orgChartName String Any random string which provides customer a mapping to resource ID No

Example orgChartName Object

{
    "orgChartName": "random_name",
}

Response Body Scheme

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.
id This is a unique resource ID on which customer can do PUT requests for sending Org Chart.

Example Response Schema

{
    "success": true,
    "id": "a356e51f-d6e8-4c08-a137-fde5368d505a"
}

Add Org Chart Endpoint

After getting a resource ID from Productiv, customer can send their data in parts by doing multiple PUT calls. 1 snapshot of org chart data should be sent with 1 resource id. Different resource ids correspond to different org chart snapshots and are used independently.

PUT https://public-api.productiv.com/services/push/v1/customer/org-chart/{id}

Include the following headers and path parameters along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token
Required Scope https://api.productiv.com/connector.write

Path Params

Parameter Description
id id represents the resource ID with which you are sending the org chartdata.

Request Body Schema

{
    "hasMore": Boolean,
    "users": [
        {
            "email": String,
            "firstName": String,
            "lastName": String,
            "team": String,
            "location": String,
            "title": String,
            "managerEmail": String,
            "additionalEmails": String
        }
    ]
}

HasMore Boolean

if the number of users you are sending in a PUT request exceeds the SLA limit (currently set to 1000 per request), set the hasMore variable as true and send the rest of the users in follow-up PUT requests. By default, if no hasMore is provided, it is assumed to be false.

User Object

Each user object has the following properties:

Property Datatype Description Optional
email String Primary Email address of an employee. Also acts as primary key. No
firstName String First Name of employee. No
lastName String Last Name of employee. No
team String Team/department of employee. No
location String Location of employee. Yes
title String Job Title of employee. Yes
managerEmail String Employee’s manager’s email. Yes
additionalEmails String Comma separated list of additional email addresses of the employee. Yes

Example User Object Schema

{
    "email": "testEmail@example.com",
    "firstName": "testFirst",
    "lastName": "testLast",
    "team": "Engineering",
    "location": "San Francisco",
    "title": "testTitle",
    "managerEmail": "testManagerEmail@example.com",
    "additionalEmails": ""
}

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.

Example Response Schema

{
    "success": true
}

API Limitations

  • Maximum of 1000 provisioned users are accepted in 1 PUT request.

Get Org Chart Endpoint

This API returns a direct link to download the latest snapshot of org chart data in CSV format.

GET https://public-api.productiv.com/services/push/v1/customer/org-chart

Include the following headers along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token
Required Scope https://api.productiv.com/report.read

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.
downloadUrl URL to download the latest Org Chart Data CSV.

Example Response Schema

{
    "success": true,
    "downloadUrl": "https://productiv-data-bucket/sample-download-link"
}

Response Errors

Error Code Error Message Description
400 Bad Request Returned if any invalid/unexpected query parameter/value is present in the request.
401 Unauthorized Returned if access_token used in request is invalid or expired.
403 Forbidden Returned if access_token does not have the required scope to use this API.
404 Not Found Returned if customer specified does not exist.
422 Unprocessable Entity Returned if the request payload is invalid.
429 Too Many Requests Returned if rate limit has been exceeded.

Example Error Response Schema

{
    "code": "401",
    "message": "Invalid access_token",
    "success": false
}