PingOne Platform APIs

Migrate existing external agreement consents to PingOne

This topic provides guidance on how to load existing user agreement consents into PingOne. It assumes that your users and agreements are already loaded into PingOne. For information about creating and managing users, refer to Users.

Your PingOne administrator must have the Identity Data Admin role to accept agreements on behalf of users.

The following terms are used to describe the PingOne and external entities:

  • External user: A user record outside of PingOne.

  • External agreement: An agreement that exists outside of PingOne to which external users have provided consent.

  • External agreement consent: A user agreement consent record outside of PingOne.

  • PingOne user: The user in PingOne. You should have a way to correlate each external user to the corresponding PingOne user.

  • PingOne agreement: An agreement in PingOne. Each of your external agreements should have a corresponding PingOne agreement.

  • PingOne agreement consent: A user agreement consent record in PingOne.

Migrate external agreement consents

Follow these steps to load one existing external user agreement consent into PingOne:

Extract the following information from your existing agreement consent record. You will need this information to complete Step 2:

  • userId

    The existing external consent should be associated with an external user. Correlate that external user to a PingOne user. The userId is that PingOne user’s id.

  • agreementId

    The existing external agreement consent should be associated with an external agreement. Correlate that external agreement to a PingOne agreement. The agreementId is that PingOne agreement’s id.

  • languageId

    The existing consent should be associated with a language. Correlate that to a PingOne agreement language. This is the PingOne agreement language languageId property value needed in the API request you will run in Step 2.

  • revisionId

    The most recent effective revision ID associated with the PingOne agreement language. This is the PingOne agreement revision revisionId property value needed in the API request you will run in Step 2.

  • consentedAt

    This can be either the external agreement consent time or the current time. If you want to make sure your users do not have to consent again, you might need to modify the PingOne agreement’s reconsent period property.

To create the user’s corresponding PingOne agreement consent, you can make requests to the following PingOne endpoint: POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementID}}. You will need the information for the external agreement consent you collected in Step 1.

The POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementID}} request uses a Content-Type header with a value of application/vnd.pingidentity.consent.accept+json to initiate the consent accept action.

The request body for this request requires the following properties:

 {
 	language: { id: "{{languageID}}" },
 	revision: { id: "{{revisionID}}" },
 	consentedAt: "{{date}}"
 }

The languageID property value is the ID of the language resource associated with the agreement revision. The revisionID is the PingOne current active agreement revision ID.

For more information about the POST {{apiPath}}/environments/{{envID}}/users/{{userID}}/agreementConsents/{{agreementConsentID}} request, refer to Accept Agreement.

To load multiple existing external user agreement consents into PingOne, you can perform this operation over your existing external agreement consents and load each one at a time. Please ensure you account for API rate limits.