PingOne Platform APIs - Early Access

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?

description

String

Optional

excludedResources

Object[]*

Optional

resourceMapping

Map

Optional

selectedResources

Object[]*

Optional

sourceEnvironment

String

Optional

targetEnvironment

Object

Required

sourceSnapshotId

String

Optional

targetSnapshotId

String

Optional

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

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"
}