--- title: Create promotion description: Create a PingOne promotion to move configuration resources from a source environment to a target environment component: pingone-api page_id: pingone-api:platform:configuration-management/promotions/create-promotion canonical_url: https://developer.pingidentity.com/pingone-api/platform/configuration-management/promotions/create-promotion.html llms_txt: https://developer.pingidentity.com/pingone-api/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-05-29 section_ids: headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Create promotion ## ```none 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](get-one-promotion.html) or [Read All Promotions](get-all-promotions.html) to view the promotion plan. > **Collapse: Request Model** > > For complete property descriptions, refer to [Promotions](index.html). > > | Property | Type | Required | > | ------------------- | ----------- | -------- | > | `description` | String | Optional | > | `excludedResources` | Object\[]\* | Optional | > | `resourceMapping` | Map | Optional | > | `selectedResources` | Object\[]\* | Optional | > | `targetEnvironment` | Object | Required | > | `sourceSnapshot` | Object | Optional | ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/json ### Body raw ( application/json ) ```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 ```shell 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" }' ``` ```csharp 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); ``` ```golang 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)) } ``` ```http 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" } ``` ```java 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(); ``` ```javascript 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); }); ``` ```javascript 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); }); ``` ```python 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 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(); } ``` ```ruby 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 ``` ```swift 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 ```json { "_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" } ```