--- title: Create Promotion component: pingone-api-ea page_id: pingone-api-ea:platform:early-access/configuration-management/promotions/create-promotion canonical_url: https://developer.pingidentity.com/pingone-api-ea/platform/early-access/configuration-management/promotions/create-promotion.html 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](../promotions.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}}" }, "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 ```shell curl --location --globoff '{{apiPath}}/v1/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" }' ``` ```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" + @" ""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); ``` ```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}}" }, "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)) } ``` ```http POST /v1/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" } ``` ```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 \"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}}/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}}" }, "selectedResources": [ "{{populationsResource}}" ], "excludedResources": [ "363ef235-f6fe-4bc7-ae3d-63217482f57f" ], "resourceMapping": { "{{sourcePopulationsResource}}": "{{targetPopulationsResource}}" }, "description": "Test promotion of population" }), }; $.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}}" }, "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); }); ``` ```python import requests import json url = "{{apiPath}}/v1/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 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 "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(); } ``` ```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}}" }, "selectedResources": [ "{{populationsResource}}" ], "excludedResources": [ "363ef235-f6fe-4bc7-ae3d-63217482f57f" ], "resourceMapping": { "{{sourcePopulationsResource}}": "{{targetPopulationsResource}}" }, "description": "Test promotion of population" }) response = http.request(request) puts response.read_body ``` ```swift 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}}/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" } ```