We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

How to pull all Site licensing users via API

In this document, we are going to provide you with the steps on how to obtain a list of all Site licensing Contract users via API.

This approach can be applied, if you'd like to build a custom data report on how many users have redeemed their site license access, the type of contract that they have redeemed, or how many licensees or contracts you have.

It may be useful if you'd like to have a report on each of your licensees, so you could determine how many users are in each contract, that might aid you in, for example, evaluating the pricing for the license on your end.

It's especially beneficial if you have a multitude of licensees, a lot of contracts or users, where viewing the statistics and data via the Piano dashboard might be sisyphean if done manually.

Step 1: List licensees

API endpoint and method:

[GET] /publisher/licensing/licensee/list

Required fields:

  • api_token (used for authentication)

  • AID

  • offset

Relevant response fields:

  • licensee_id

This API endpoint will provide you with a list of all your Site Licensees (and their respective licensee IDs) that you can further utilize in the next step.

Step 2: List contracts for each licensee

API endpoint and method:

[GET] /publisher/licensing/contract/list

Required fields:

  • licensee_id (retrieved from the response of the API endpoint in Step 1)

  • api_token (used for authentication)

  • AID

  • offset

Relevant response fields:

  • contract_id

  • contract_type (The response with the values "SPECIFIC_EMAIL_ADDRESSES_CONTRACT" or "EMAIL_DOMAIN_CONTRACT" will define if you need to use the contract_id in Step 3 or Step 4)

This API endpoint will provide you with the contract ID for each of your Site licensees.

Note, if you have received multiple licensee IDs as a response to the endpoint from Step 1, you will need to call the endpoint from Step 2 for each of these separately.

Step 3: List contract users for each contract

API endpoint and method:

[GET] /publisher/licensing/contractUser/list

Required fields:

  • contract_id (retrieved from the response of the API endpoint in Step 2)

  • api_token (used for authentication)

  • AID

  • offset

Relevant response fields:

  • email

  • first_name

  • last_name

  • status

This endpoint will provide you with a list of all email address contract users for the specified contract with the contract_type "SPECIFIC_EMAIL_ADDRESSES_CONTRACT".

Note, if you have received multiple contract IDs as a response to the endpoint from Step 2, you will need to call the endpoint from Step 3 for each of these separately.

Step 4: List contract domains for each contract

API endpoint and method:

[GET] /publisher/licensing/contractDomain/list

Required fields:

  • contract_id (retrieved from the response of the API endpoint in Step 2)

  • api_token (used for authentication)

  • AID

  • offset

Relevant response fields:

  • contract_domain_id

  • contract_domain_value

This endpoint will provide you with a list of all email domains and their contract domain IDs for the specified with the contract_type "EMAIL_DOMAIN_CONTRACT".

Note, if you have received multiple contract IDs as a response to the endpoint from Step 2, you will need to call the endpoint from Step 4 for each of these separately.

Step 5: List contract users for each contract domain

API endpoint and method:

[GET] /publisher/licensing/contractDomain/contractUser/list

Required fields:

  • contract_id (retrieved from the response of the API endpoint in Step 2)

  • contract_domain_id (retrieved from the response of the API endpoint in Step 4)

  • api_token (used for authentication)

  • AID

  • offset

Relevant response fields:

  • email

  • first_name

  • last_name

  • status

This endpoint will provide you with a list of all users for the respective contract domain IDs. (Retrieved via Step 4)

Note, if you have received multiple contract domain IDs as a response to the endpoint from Step 4, you will need to call the endpoint from Step 5 for each of these separately.

Last updated: