Create Promotion
POST {{apiPath}}/environments/{{envID}}/promotions
Use POST {{apiPath}}/environments/{{envID}}/promotions to create a promotion for the specified configuration resource or resources in the source and target environments. You need to have the Environment Admin role for both the source and target environments.
When you create a promotion, you’ve the option to specify a snapshot of the configuration resource or resources for the source or target environments, or allow the Configuration Management service to automatically generate snapshots for both. You’ve also the option to specify a mapping between the source and target configuration resource or resources. If you don’t specify a mapping, the source and target environment snapshots are compared, and a mapping between the source and target configuration resources is automatically calculated. After the comparison, the promotion is stored with the mapping, and a promotion plan is automatically generated. Use the Read One Promotion or Read All Promotions to view the promotion plan.
Request Model
For complete property descriptions, refer to Promotions.
| Property | Type | Required? |
|---|---|---|
|
String |
Optional |
|
Object[]* |
Optional |
|
Map |
Optional |
|
Object[]* |
Optional |
|
String |
Optional |
|
Object |
Required |
|
String |
Optional |
|
String |
Optional |
Body
raw ( application/json )
{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion of population"
}
Example Request
-
cURL
-
C#
-
Go
-
HTTP
-
Java
-
jQuery
-
NodeJS
-
Python
-
PHP
-
Ruby
-
Swift
curl --location --globoff '{{apiPath}}/environments/{{envID}}/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion of population"
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/promotions")
{
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" +
@" ""targetEnvironment"": {" + "\n" +
@" ""id"": ""{{targetEnvID}}""" + "\n" +
@" }," + "\n" +
@" ""selectedResources"": [" + "\n" +
@" ""{{populationsResource}}""" + "\n" +
@" ]," + "\n" +
@" ""excludedResources"": [" + "\n" +
@" ""363ef235-f6fe-4bc7-ae3d-63217482f57f""" + "\n" +
@"" + "\n" +
@" ]," + "\n" +
@" ""resourceMapping"": {""{{sourcePopulationsResource}}"":""{{targetPopulationsResource}}""}," + "\n" +
@" ""description"": ""Test promotion of population""" + "\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}}/promotions"
method := "POST"
payload := strings.NewReader(`{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion of population"
}`)
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}}/promotions HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}
{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion of population"
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"targetEnvironment\": {\n \"id\": \"{{targetEnvID}}\"\n },\n \"selectedResources\": [\n \"{{populationsResource}}\"\n ],\n \"excludedResources\": [\n \"363ef235-f6fe-4bc7-ae3d-63217482f57f\"\n\n ],\n \"resourceMapping\": {\"{{sourcePopulationsResource}}\":\"{{targetPopulationsResource}}\"},\n \"description\": \"Test promotion of population\"\n}");
Request request = new Request.Builder()
.url("{{apiPath}}/environments/{{envID}}/promotions")
.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}}/promotions",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}"
},
"data": JSON.stringify({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion of population"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var request = require('request');
var options = {
'method': 'POST',
'url': '{{apiPath}}/environments/{{envID}}/promotions',
'headers': {
'Content-Type': 'application/json',
'Authorization': 'Bearer {{accessToken}}'
},
body: JSON.stringify({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion of population"
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{{apiPath}}/environments/{{envID}}/promotions"
payload = json.dumps({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion of population"
})
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}}/promotions');
$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 "targetEnvironment": {\n "id": "{{targetEnvID}}"\n },\n "selectedResources": [\n "{{populationsResource}}"\n ],\n "excludedResources": [\n "363ef235-f6fe-4bc7-ae3d-63217482f57f"\n\n ],\n "resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},\n "description": "Test promotion of population"\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}}/promotions")
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({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"selectedResources": [
"{{populationsResource}}"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion of population"
})
response = http.request(request)
puts response.read_body
let parameters = "{\n \"targetEnvironment\": {\n \"id\": \"{{targetEnvID}}\"\n },\n \"selectedResources\": [\n \"{{populationsResource}}\"\n ],\n \"excludedResources\": [\n \"363ef235-f6fe-4bc7-ae3d-63217482f57f\"\n\n ],\n \"resourceMapping\": {\"{{sourcePopulationsResource}}\":\"{{targetPopulationsResource}}\"},\n \"description\": \"Test promotion of population\"\n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/promotions")!,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/promotions/e2cf9a22-5aeb-4046-ad3d-c6dc97c90ef9"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"targetEnvironment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"sourceSnapshot": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/snapshots/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/versions/0c31da80-8588-4ec1-8837-ad7f7aa94884"
},
"targetSnapshot": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/snapshots/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/versions/9f6f1184-6d61-4a42-8115-136c34574d8d"
},
"promotionSteps": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/promotions/e2cf9a22-5aeb-4046-ad3d-c6dc97c90ef9/promotionSteps"
}
},
"id": "e2cf9a22-5aeb-4046-ad3d-c6dc97c90ef9",
"createdAt": "2025-07-04T15:29:43.199Z",
"updatedAt": "2025-07-04T15:29:43.199Z",
"sourceEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"targetEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"sourceSnapshotId": "0c31da80-8588-4ec1-8837-ad7f7aa94884",
"targetSnapshotId": "9f6f1184-6d61-4a42-8115-136c34574d8d",
"status": "NEW",
"selectedResources": [
"26a126c2-054f-4f18-b077-8226c0c4bf3e"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"26a126c2-054f-4f18-b077-8226c0c4bf3e": "c7c92d16-e07b-4ddb-8d17-073fea3a219c"
},
"description": "Test promotion of population"
}
Example Response
201 Created
{
"_links": {
"self": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/promotions/d7f29675-9a1b-4775-a047-a0d359003e0a"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"targetEnvironment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"sourceSnapshot": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/snapshots/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/versions/73a64c05-d67d-49fb-8430-9dc86634e528"
},
"targetSnapshot": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/snapshots/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/versions/f411cd3d-a3e3-46c4-b2b2-8571d11fc7ce"
}
},
"id": "d7f29675-9a1b-4775-a047-a0d359003e0a",
"createdAt": "2024-09-06T14:42:36.749Z",
"updatedAt": "2024-09-06T14:42:36.749Z",
"sourceEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"rootResourceId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"targetEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"sourceSnapshotId": "73a64c05-d67d-49fb-8430-9dc86634e528",
"targetSnapshotId": "f411cd3d-a3e3-46c4-b2b2-8571d11fc7ce",
"status": "NEW",
"selectedResources": [
"abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
],
"description": "Test promotion of entire environment"
}