Publish Provisioned Users

Productiv tracks the set of users that are provisioned for an application, in order to show accurate rightsizing and inactivity numbers in the product. A user is usually considered provisioned if they are using a license or are being paid for by the enterprise, although this is not always the case. On Productiv's platform, the recommended way to decide whether or not a user is provisioned, is to decide whether or not you care about their activity. If the answer to that question is yes, then you most likely want to consider that user provisioned. Every application usually has a different definition on whether or not a user is provisioned. For example, some applications consider a user provisioned even if the user is just invited, since the license is still assigned to them and not available for use anymore. Applications usually have different policies for this based on inactivity or some user state such as invited, suspended, etc. When publishing a set of provisioned users for an application, it will be up to the developer to decide which of these factors decide user provisioning.

These APIs can be used to add, modify, and delete the collection of provisioned users for an application in Productiv. Productiv will always treat the set of provisioned users updated by these API's as the current list of all users for the application.

Prerequisites

  • Before this API can be queried you should have already setup the application for which you will be publishing provisioned users. Once thats done you should have a unique appId that can be used to query these APIs. To see how to setup an application checkout Setup an Application.

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

Add Provisioned Users Endpoint

POST https://api.productiv.com/services/push/v1/customer/apps/{appId}/users

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

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token

Path Params

Parameter Description
appId appId represents the App for which the provisioned users are being pushed.

Request Body Schema

{
    "provisionedUsers": [{
       "email": String,
       "appUserId": String,
       "username": String,
       "license": String
    }]
}

Provisioned User Object

Every provisioned user should have the following properties in the object:

Property Datatype Description Optional
email String Email of the provisioned user No
appUserId String User Id of the provisioned user for the specified application No
username String Username of provisioned user Yes
license String License associated with this provisioned user Yes

Example Provisioned User Object Schema

{
    "appUserId": "109282355904833424637",
    "email": "testuser@random.com",
    "username": "testuser",
    "license": "Pro"
}

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

  • Add maximum of 1000 provisioned users at a time

SLA

  • Any changes to user provisioning will be reflected for any data aggregations run for after 24 hours of the change date
  • All users added by this API are considered provisioned

Delete Provisioned Users Endpoint

DELETE https://api.productiv.com/services/push/v1/customer/apps/{appId}/users

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

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token

Path Params

Parameter Description
appId appId represents the App for which the provisioned users are being deleted.

Request Body Schema

{
    "provisionedUsers": [{
       "email": String,
       "appUserId": String,
       "username": String,
       "license": String
    }]
}

Provisioned User Object

Every provisioned user should have the following properties in the object:

Property Datatype Description Optional
email String Email of the provisioned user No
appUserId String User Id of the provisioned user for the specified application No
username String Username of provisioned user Yes
license String License associated with this provisioned user Yes

Example Provisioned User Object Schema

{
    "appUserId": "109282355904833424637",
    "email": "testuser@random.com"
}

Response

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

Parameter Description
numUsersDeleted The number of users removed from provisioning information
success Will be set to true in case of a successful response where all users are deleted.
nonDeletedUsers List of valid provisioned users that could not be deleted in the request. Retrying of deletion of any users in this list acceptable with 500 error code.

Example Response Schema

{
    "success": true
}

API Limitations

  • Delete maximum of 1000 provisioned users at a time

SLA

  • Any changes to user provisioning will be reflected within 24 hours of the change date

Get Provisioned Users Endpoint

GET https://api.productiv.com/services/push/v1/customer/apps/{appId}/users

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

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token

Path Params

Parameter Description
appId appId represents the App for which the provisioned users are being retrieved.

Query Params

Parameter Description
nextPageToken Opaque token that can be specified to get the next page of provisioned users from the last request

Provisioned User Object

Every provisioned user should have the following properties in the object:

Property Datatype Description Optional
email String Email of the provisioned user No
appUserId String User Id of the provisioned user for the specified application No
username String Username of provisioned user Yes
license String License associated with this provisioned user Yes

Example Provisioned User Object Schema

{
    "appUserId": "109282355904833424637",
    "email": "testuser@random.com",
    "username": "testuser",
    "license": "Pro"
}

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.
provisionedUsers Array of provisioned users in the Provisioned User Object schema.
nextPageToken Token to retrieve next page of users from current request. Null if no next page.
numUsers The number of users in this page of provisioned users

Example Response Schema

{
    "numUsers": 1,
    "success": true,
    "provisionedUsers": [
      {
        "appUserId": "109282355904833424637",
        "email": "testuser@random.com",
        "username": "testuser",
        "license": "Pro"
      }
    ],
    "nextPageToken": null,
    "totalPages": 1
}

Pagination

  • This API will retrieve maximum of 1000 users at a time. All subsequent calls to get more users must be called with the nextPageToken.

SLA

  • Any changes to user provisioning will be reflected for any data aggregations for 24 hours after the change date

API Response Error Codes

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 or application 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,
}
{
    "code": "400",
    "message": "Invalid nextPageToken",
    "success": false,
}

Rate limit

Coming Soon