PingOne Platform APIs

Create Revision

 

POST {{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions

The POST {{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions endpoint creates a new revision resource in the specified environment.

The request body must include values for the effectiveAt, requireReconsent, and text properties.

When setting the agreement revision’s effectiveAt property to a variable such as {{now}}, you need to calculate the now value and set it as an ISO timestamp (for example, 2022-04-27T21:40:58.467Z). Also, verify that your computer’s Set date and time automatically system property is enabled. If it is disabled, it could result in a discrepancy that causes an error when setting the effective date. The browser’s javascript depends on the machine’s running time to save the agreement revision date.

The response does not include the text property. To access this value, use the _links.text URL.

Prerequisites

  • Refer to Agreement Management for important overview information.

  • Before you can create an agreement consent revision in a specific language for the consent, you must set a default language for the environment using the Language Management APIs. Refer to Create Language and Read Languages.

  • Create an agreement to get an agreementID. Refer to Create Agreement.

  • Create a language to get a languageID. Refer to Create Language.

Request Model

For property descriptions, refer to Revision data model.

Property Type Required?

effectiveAt

Date

Required

requiresReconsent

Boolean

Required

text

String

Required

contentType

String

Required

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": false,
  "text": "Test, test, test",
  "contentType": "text/plain"
}

Example Request

  • cURL

  • C#

  • Go

  • HTTP

  • Java

  • jQuery

  • NodeJS

  • Python

  • PHP

  • Ruby

  • Swift

curl --location --globoff '{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": false,
  "text": "Test, test, test",
  "contentType": "text/plain"
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"  ""effectiveAt"": ""2098-08-01T22:45:44.497Z""," + "\n" +
@"  ""requireReconsent"": false," + "\n" +
@"  ""text"": ""Test, test, test""," + "\n" +
@"  ""contentType"": ""text/plain""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions"
  method := "POST"

  payload := strings.NewReader(`{
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": false,
  "text": "Test, test, test",
  "contentType": "text/plain"
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}
POST /environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": false,
  "text": "Test, test, test",
  "contentType": "text/plain"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"effectiveAt\": \"2098-08-01T22:45:44.497Z\",\n  \"requireReconsent\": false,\n  \"text\": \"Test, test, test\",\n  \"contentType\": \"text/plain\"\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();
var settings = {
  "url": "{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "effectiveAt": "2098-08-01T22:45:44.497Z",
    "requireReconsent": false,
    "text": "Test, test, test",
    "contentType": "text/plain"
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});
var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "effectiveAt": "2098-08-01T22:45:44.497Z",
    "requireReconsent": false,
    "text": "Test, test, test",
    "contentType": "text/plain"
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
import requests
import json

url = "{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions"

payload = json.dumps({
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": False,
  "text": "Test, test, test",
  "contentType": "text/plain"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n  "effectiveAt": "2098-08-01T22:45:44.497Z",\n  "requireReconsent": false,\n  "text": "Test, test, test",\n  "contentType": "text/plain"\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}
require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "effectiveAt": "2098-08-01T22:45:44.497Z",
  "requireReconsent": false,
  "text": "Test, test, test",
  "contentType": "text/plain"
})

response = http.request(request)
puts response.read_body
let parameters = "{\n  \"effectiveAt\": \"2098-08-01T22:45:44.497Z\",\n  \"requireReconsent\": false,\n  \"text\": \"Test, test, test\",\n  \"contentType\": \"text/plain\"\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/agreements/{{agreementID}}/languages/{{languageID}}/revisions")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

201 Created

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/agreements/d462d436-cf80-421c-8c05-881e9958c4b4/languages/7e156496-4e67-4adc-a139-ebbbbe2c1aea/revisions/aab73db4-9432-4149-9d24-daa8e6e1289b"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        },
        "agreement": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/agreements/d462d436-cf80-421c-8c05-881e9958c4b4"
        },
        "language": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/agreements/d462d436-cf80-421c-8c05-881e9958c4b4/languages/7e156496-4e67-4adc-a139-ebbbbe2c1aea"
        },
        "text": {
            "href": "https://agreement-mgmt.pingone.com/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/agreements/d462d436-cf80-421c-8c05-881e9958c4b4/languages/7e156496-4e67-4adc-a139-ebbbbe2c1aea/revisions/aab73db4-9432-4149-9d24-daa8e6e1289b.json"
        }
    },
    "id": "aab73db4-9432-4149-9d24-daa8e6e1289b",
    "environment": {
        "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
    },
    "agreement": {
        "id": "d462d436-cf80-421c-8c05-881e9958c4b4"
    },
    "language": {
        "id": "7e156496-4e67-4adc-a139-ebbbbe2c1aea"
    },
    "effectiveAt": "2098-08-01T22:45:44.497Z",
    "contentType": "text/plain",
    "requireReconsent": false
}