--- title: Create User description: The POST {{apiPath}}/v1/environments/{{envID}}/users operation adds a new user resource to the specified environment. component: pingone-api page_id: pingone-api:platform:users/users-1/create-user canonical_url: https://developer.pingidentity.com/pingone-api/platform/users/users-1/create-user.html section_ids: prerequisites: Prerequisites headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Create User ## ```none POST {{apiPath}}/v1/environments/{{envID}}/users ``` The `POST {{apiPath}}/v1/environments/{{envID}}/users` operation adds a new user resource to the specified environment. This operation does not support an attribute to set the new user's password. To create a user and set the password, refer to [Import a user](create-user-import.html). For information about setting a user's password after creating the new user, refer to [Set password](../user-passwords/update-password-set.html). New users must be assigned to the default population for the environment, if one exists, and if the population ID is not provided in the request. The request must also set a value for the `username` attribute. The `username` value is case-insensitive, and must be unique to an environment (spanning populations). Access to populations is determined by roles. It's possible that `username` conflicts may arise, if you or your worker application attempt to create a user that exists in a population to which you have no access. New users who are not authenticating with PingOne must be assigned an identity provider with the `identityProvider.id` attribute. If `identityProvider.id` is not provided, PingOne is set as the default identity provider. The `identityProvider.type` value is read-only, and its value is dependent on the value of `identityProvider.id`. If `identityProvider.id` is not provided, the default value of `identityProvider.type` is `PING_ONE`. In the example, locales is a multi-valued custom attribute. Its value must be an array, regardless of the number of values provided. Refer to [Custom attributes](../../schemas.html) in Schemas for more information. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can enable multi-factor authentication by setting `mfaEnabled` to `true` with [POST Create User](create-user.html), [POST Create User (Import)](create-user-import.html), or [PUT Update User MFA Enabled](../../../mfa/users/enable-users-mfa/update-user-mfa-enabled.html). You cannot update `mfaEnabled` with [PUT Update User](update-user-put.html) or [PATCH Update User](update-user-patch.html). | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you're intending to set a custom attribute on the user, you'll need to first create the custom attribute for the schema using [Create Attribute](../../schemas/create-attribute.html). If you neglect to do this, the custom attribute values are ignored when the user is created. | If successful, the response returns a `201 Successfully created` message and shows the new user resource's property data. ### Prerequisites * Refer to [Users](../../users.html) and [User Operations](../users-1.html) for important overview information. * Create a population to get a `popID`. Refer to [Create Population](../../populations/create-population.html). Run [Read All Populations](../../populations/read-all-populations.html) to find an existing population. > **Collapse: Request Model** > > | Property | Type | Required? | > | ----------------------- | --------------- | --------- | > | `accountId` | String | Optional | > | `address.streetAddress` | String | Optional | > | `address.countryCode` | String | Optional | > | `address.locality` | String | Optional | > | `address.region` | String | Optional | > | `address.postalCode` | String | Optional | > | `address.zipCode` | String | Optional | > | `email` | String | Optional | > | `locale` | Array \[String] | Optional | > | `mobilePhone` | String | Optional | > | `name.given` | String | Optional | > | `name.family` | String | Optional | > | `name.middle` | String | Optional | > | `name.honorificPrefix` | String | Optional | > | `name.honorificSuffix` | String | Optional | > | `name.formatted` | String | Optional | > | `nickname` | String | Optional | > | `photo.href` | String | Optional | > | `population.id` | String | Required | > | `preferredLanguage` | String | Optional | > | `primaryPhone` | String | Optional | > | `timeZone` | String | Optional | > | `title` | String | Optional | > | `type` | String | Optional | > | `username` | String | Required | > > Refer to the [User operations](../users-1.html) data model for full property descriptions. ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/json ### Body raw ( application/json ) ```json { "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": ["Sydney", "London"] } ``` ## ### Example Request * cURL * C# * Go * HTTP * Java * jQuery * NodeJS * Python * PHP * Ruby * Swift ```shell curl --location --globoff '{{apiPath}}/v1/environments/{{envID}}/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{accessToken}}' \ --data-raw '{ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": ["Sydney", "London"] }' ``` ```csharp var options = new RestClientOptions("{{apiPath}}/v1/environments/{{envID}}/users") { 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" + @" ""email"": ""marysample@example.com""," + "\n" + @" ""name"": {" + "\n" + @" ""given"": ""Mary""," + "\n" + @" ""family"": ""Sample""" + "\n" + @" }," + "\n" + @" ""population"": {" + "\n" + @" ""id"": ""{{popID}}""" + "\n" + @" }," + "\n" + @" ""username"": ""marysample""," + "\n" + @" ""department"": ""engineering""," + "\n" + @" ""locales"": [""Sydney"", ""London""]" + "\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}}/users" method := "POST" payload := strings.NewReader(`{ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": ["Sydney", "London"] }`) 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}}/users HTTP/1.1 Host: {{apiPath}} Content-Type: application/json Authorization: Bearer {{accessToken}} { "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": ["Sydney", "London"] } ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"email\": \"marysample@example.com\",\n \"name\": {\n \"given\": \"Mary\",\n \"family\": \"Sample\"\n },\n \"population\": {\n \"id\": \"{{popID}}\"\n },\n \"username\": \"marysample\",\n \"department\": \"engineering\",\n \"locales\": [\"Sydney\", \"London\"]\n}"); Request request = new Request.Builder() .url("{{apiPath}}/v1/environments/{{envID}}/users") .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}}/users", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/json", "Authorization": "Bearer {{accessToken}}" }, "data": JSON.stringify({ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": [ "Sydney", "London" ] }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': '{{apiPath}}/v1/environments/{{envID}}/users', 'headers': { 'Content-Type': 'application/json', 'Authorization': 'Bearer {{accessToken}}' }, body: JSON.stringify({ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": [ "Sydney", "London" ] }) }; 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}}/users" payload = json.dumps({ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": [ "Sydney", "London" ] }) 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}}/users'); $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 "email": "marysample@example.com",\n "name": {\n "given": "Mary",\n "family": "Sample"\n },\n "population": {\n "id": "{{popID}}"\n },\n "username": "marysample",\n "department": "engineering",\n "locales": ["Sydney", "London"]\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}}/users") 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({ "email": "marysample@example.com", "name": { "given": "Mary", "family": "Sample" }, "population": { "id": "{{popID}}" }, "username": "marysample", "department": "engineering", "locales": [ "Sydney", "London" ] }) response = http.request(request) puts response.read_body ``` ```swift let parameters = "{\n \"email\": \"marysample@example.com\",\n \"name\": {\n \"given\": \"Mary\",\n \"family\": \"Sample\"\n },\n \"population\": {\n \"id\": \"{{popID}}\"\n },\n \"username\": \"marysample\",\n \"department\": \"engineering\",\n \"locales\": [\"Sydney\", \"London\"]\n}" let postData = parameters.data(using: .utf8) var request = URLRequest(url: URL(string: "{{apiPath}}/v1/environments/{{envID}}/users")!,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/users/8376797d-641c-4e7b-8bc1-2fdf71916cab" }, "environment": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "population": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/populations/60971d3b-cc5a-4601-9c44-2be541f91bf1" }, "devices": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/devices" }, "roleAssignments": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/roleAssignments" }, "password": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.reset": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.set": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.check": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "password.recover": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/password" }, "linkedAccounts": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab/linkedAccounts" }, "account.sendVerificationCode": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/8376797d-641c-4e7b-8bc1-2fdf71916cab" } }, "id": "8376797d-641c-4e7b-8bc1-2fdf71916cab", "environment": { "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "population": { "id": "60971d3b-cc5a-4601-9c44-2be541f91bf1" }, "createdAt": "2020-02-18T20:50:14.092Z", "email": "tomjones@example.com", "enabled": true, "lifecycle": { "status": "ACCOUNT_OK" }, "mfaEnabled": false, "name": { "given": "Tom", "family": "Jones" }, "locales": [ "Sydney", "London" ], "updatedAt": "2020-02-18T20:50:14.092Z", "username": "tomjones" } ```