Create Promotion
POST {{apiPath}}/v1/environments/{{envID}}/promotions
Use POST {{apiPath}}/v1/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 |
|
Object |
Required |
|
Object |
Optional |
Body
raw ( application/json )
{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion"
}
Example Request
-
cURL
-
C#
-
Go
-
HTTP
-
Java
-
jQuery
-
NodeJS
-
Python
-
PHP
-
Ruby
-
Swift
curl --location --globoff '{{apiPath}}/v1/environments/{{envID}}/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion"
}'
var options = new RestClientOptions("{{apiPath}}/v1/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" +
@" ""sourceSnapshot"": {" + "\n" +
@" ""id"": ""{{sourceSnapshotId}}""" + "\n" +
@" }," + "\n" +
@" ""selectedResources"": [" + "\n" +
@" ""09facb42-b428-4590-aaba-1f4278f4ed63""" + "\n" +
@" ]," + "\n" +
@" ""excludedResources"": [" + "\n" +
@" ""363ef235-f6fe-4bc7-ae3d-63217482f57f""" + "\n" +
@"" + "\n" +
@" ]," + "\n" +
@" ""resourceMapping"": {""{{sourcePopulationsResource}}"":""{{targetPopulationsResource}}""}," + "\n" +
@" ""description"": ""Test promotion""" + "\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}}/v1/environments/{{envID}}/promotions"
method := "POST"
payload := strings.NewReader(`{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion"
}`)
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 /v1/environments/{{envID}}/promotions HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}
{
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},
"description": "Test promotion"
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"targetEnvironment\": {\n \"id\": \"{{targetEnvID}}\"\n },\n \"sourceSnapshot\": {\n \"id\": \"{{sourceSnapshotId}}\"\n },\n \"selectedResources\": [\n \"09facb42-b428-4590-aaba-1f4278f4ed63\"\n ],\n \"excludedResources\": [\n \"363ef235-f6fe-4bc7-ae3d-63217482f57f\"\n\n ],\n \"resourceMapping\": {\"{{sourcePopulationsResource}}\":\"{{targetPopulationsResource}}\"},\n \"description\": \"Test promotion\"\n}");
Request request = new Request.Builder()
.url("{{apiPath}}/v1/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}}/v1/environments/{{envID}}/promotions",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}"
},
"data": JSON.stringify({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion"
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var request = require('request');
var options = {
'method': 'POST',
'url': '{{apiPath}}/v1/environments/{{envID}}/promotions',
'headers': {
'Content-Type': 'application/json',
'Authorization': 'Bearer {{accessToken}}'
},
body: JSON.stringify({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion"
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{{apiPath}}/v1/environments/{{envID}}/promotions"
payload = json.dumps({
"targetEnvironment": {
"id": "{{targetEnvID}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion"
})
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}}/v1/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 "sourceSnapshot": {\n "id": "{{sourceSnapshotId}}"\n },\n "selectedResources": [\n "09facb42-b428-4590-aaba-1f4278f4ed63"\n ],\n "excludedResources": [\n "363ef235-f6fe-4bc7-ae3d-63217482f57f"\n\n ],\n "resourceMapping": {"{{sourcePopulationsResource}}":"{{targetPopulationsResource}}"},\n "description": "Test promotion"\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}}/v1/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}}"
},
"sourceSnapshot": {
"id": "{{sourceSnapshotId}}"
},
"selectedResources": [
"09facb42-b428-4590-aaba-1f4278f4ed63"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"{{sourcePopulationsResource}}": "{{targetPopulationsResource}}"
},
"description": "Test promotion"
})
response = http.request(request)
puts response.read_body
let parameters = "{\n \"targetEnvironment\": {\n \"id\": \"{{targetEnvID}}\"\n },\n \"sourceSnapshot\": {\n \"id\": \"{{sourceSnapshotId}}\"\n },\n \"selectedResources\": [\n \"09facb42-b428-4590-aaba-1f4278f4ed63\"\n ],\n \"excludedResources\": [\n \"363ef235-f6fe-4bc7-ae3d-63217482f57f\"\n\n ],\n \"resourceMapping\": {\"{{sourcePopulationsResource}}\":\"{{targetPopulationsResource}}\"},\n \"description\": \"Test promotion\"\n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "{{apiPath}}/v1/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/a8fa2955-63ce-441e-87ed-57e9e92404e4"
},
"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/17044f5a-8dc3-42d9-9db1-683df0965ff2"
},
"targetSnapshot": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/snapshots/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/versions/657fe011-b198-4efa-bd15-14d6425509fb"
},
"promotionSteps": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/promotions/a8fa2955-63ce-441e-87ed-57e9e92404e4/promotionSteps"
}
},
"id": "a8fa2955-63ce-441e-87ed-57e9e92404e4",
"createdAt": "2026-05-25T17:55:39.850Z",
"updatedAt": "2026-05-25T17:55:39.850Z",
"sourceEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"sourceEnvironment": {
"id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"targetEnvironmentId": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6",
"targetEnvironment": {
"id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"sourceSnapshotId": "17044f5a-8dc3-42d9-9db1-683df0965ff2",
"sourceSnapshot": {
"id": "17044f5a-8dc3-42d9-9db1-683df0965ff2"
},
"targetSnapshotId": "657fe011-b198-4efa-bd15-14d6425509fb",
"targetSnapshot": {
"id": "657fe011-b198-4efa-bd15-14d6425509fb"
},
"status": "NEW",
"selectedResources": [
"26a126c2-054f-4f18-b077-8226c0c4bf3e"
],
"excludedResources": [
"363ef235-f6fe-4bc7-ae3d-63217482f57f"
],
"resourceMapping": {
"2c3b1245-2c38-4174-97fa-069d88a543b1": "c7c92d16-e07b-4ddb-8d17-073fea3a219c"
},
"description": "Test promotion of population"
}