--- title: Search Using POST with Controls description: This POST /directory/v1/{{dn}}/subtree/search adds a _controls property to the requests and responses for the search action. The property is an array of JSON formatted controls that are used to include additional content in LDAP requests and responses. For more information about supported controls, refer to Controls. component: pingdirectory page_id: pingdirectory:directory:subtree-apis/search-using-post-with-controls canonical_url: https://developer.pingidentity.com/pingdirectory/directory/subtree-apis/search-using-post-with-controls.html section_ids: headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Search Using POST with Controls ## ```none POST {{apiPath}}/directory/v1/{{dn}}/subtree/search ``` This `POST /directory/v1/{{dn}}/subtree/search` adds a `_controls` property to the requests and responses for the search action. The property is an array of JSON formatted controls that are used to include additional content in LDAP requests and responses. For more information about supported controls, refer to [Controls](../controls.html). The sample shows a search request that includes two controls, a join request control and permit unindexed search request control. The response body includes an additional `_controls` property that shows the join result control JSON. | | | | - | -------------------------------------------------------------------------- | | | The `_controls` property is only supported for PingDirectory 9.1 or later. | ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/json ### Body raw ( application/json ) ```json { "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] } ``` ## ### Example Request * cURL * C# * Go * HTTP * Java * jQuery * NodeJS * Python * PHP * Ruby * Swift ```shell curl --location --globoff '{{apiPath}}/directory/v1/{{dn}}/subtree/search' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{accessToken}}' \ --data '{ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] }' ``` ```csharp var options = new RestClientOptions("{{apiPath}}/directory/v1/{{dn}}/subtree/search") { 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" + @" ""filter"": ""uid eq \""user.68\""""," + "\n" + @" ""searchScope"": ""wholeSubtree""," + "\n" + @" ""_controls"": [" + "\n" + @" {" + "\n" + @" ""oid"": ""1.3.6.1.4.1.30221.2.5.9""," + "\n" + @" ""control-name"": ""Join Request Control""," + "\n" + @" ""criticality"": false," + "\n" + @" ""value-json"": {" + "\n" + @" ""join-rule"": {" + "\n" + @" ""type"": ""dn""," + "\n" + @" ""source-attribute"": ""manager""" + "\n" + @" }," + "\n" + @" ""base-dn-type"": ""use-search-base-dn""," + "\n" + @" ""require-match"": false" + "\n" + @" }" + "\n" + @" }," + "\n" + @" {" + "\n" + @" ""oid"": ""1.3.6.1.4.1.30221.2.5.55""," + "\n" + @" ""control-name"": ""Permit Unindexed Search Request Control""," + "\n" + @" ""criticality"": true" + "\n" + @" }" + "\n" + @" ]" + "\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}}/directory/v1/{{dn}}/subtree/search" method := "POST" payload := strings.NewReader(`{ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] }`) 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 /directory/v1/{{dn}}/subtree/search HTTP/1.1 Host: {{apiPath}} Content-Type: application/json Authorization: Bearer {{accessToken}} { "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] } ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"filter\": \"uid eq \\\"user.68\\\"\",\n \"searchScope\": \"wholeSubtree\",\n \"_controls\": [\n {\n \"oid\": \"1.3.6.1.4.1.30221.2.5.9\",\n \"control-name\": \"Join Request Control\",\n \"criticality\": false,\n \"value-json\": {\n \"join-rule\": {\n \"type\": \"dn\",\n \"source-attribute\": \"manager\"\n },\n \"base-dn-type\": \"use-search-base-dn\",\n \"require-match\": false\n }\n },\n {\n \"oid\": \"1.3.6.1.4.1.30221.2.5.55\",\n \"control-name\": \"Permit Unindexed Search Request Control\",\n \"criticality\": true\n }\n ]\n}"); Request request = new Request.Builder() .url("{{apiPath}}/directory/v1/{{dn}}/subtree/search") .method("POST", body) .addHeader("Content-Type", "application/json") .addHeader("Authorization", "Bearer {{accessToken}}") .build(); Response response = client.newCall(request).execute(); ``` ```javascript var settings = { "url": "{{apiPath}}/directory/v1/{{dn}}/subtree/search", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/json", "Authorization": "Bearer {{accessToken}}" }, "data": JSON.stringify({ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': '{{apiPath}}/directory/v1/{{dn}}/subtree/search', 'headers': { 'Content-Type': 'application/json', 'Authorization': 'Bearer {{accessToken}}' }, body: JSON.stringify({ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` ```python import requests import json url = "{{apiPath}}/directory/v1/{{dn}}/subtree/search" payload = json.dumps({ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": False, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": False } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": True } ] }) headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer {{accessToken}}' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` ```php setUrl('{{apiPath}}/directory/v1/{{dn}}/subtree/search'); $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 "filter": "uid eq \\"user.68\\"",\n "searchScope": "wholeSubtree",\n "_controls": [\n {\n "oid": "1.3.6.1.4.1.30221.2.5.9",\n "control-name": "Join Request Control",\n "criticality": false,\n "value-json": {\n "join-rule": {\n "type": "dn",\n "source-attribute": "manager"\n },\n "base-dn-type": "use-search-base-dn",\n "require-match": false\n }\n },\n {\n "oid": "1.3.6.1.4.1.30221.2.5.55",\n "control-name": "Permit Unindexed Search Request Control",\n "criticality": true\n }\n ]\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}}/directory/v1/{{dn}}/subtree/search") 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({ "filter": "uid eq \"user.68\"", "searchScope": "wholeSubtree", "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Request Control", "criticality": false, "value-json": { "join-rule": { "type": "dn", "source-attribute": "manager" }, "base-dn-type": "use-search-base-dn", "require-match": false } }, { "oid": "1.3.6.1.4.1.30221.2.5.55", "control-name": "Permit Unindexed Search Request Control", "criticality": true } ] }) response = http.request(request) puts response.read_body ``` ```swift let parameters = "{\n \"filter\": \"uid eq \\\"user.68\\\"\",\n \"searchScope\": \"wholeSubtree\",\n \"_controls\": [\n {\n \"oid\": \"1.3.6.1.4.1.30221.2.5.9\",\n \"control-name\": \"Join Request Control\",\n \"criticality\": false,\n \"value-json\": {\n \"join-rule\": {\n \"type\": \"dn\",\n \"source-attribute\": \"manager\"\n },\n \"base-dn-type\": \"use-search-base-dn\",\n \"require-match\": false\n }\n },\n {\n \"oid\": \"1.3.6.1.4.1.30221.2.5.55\",\n \"control-name\": \"Permit Unindexed Search Request Control\",\n \"criticality\": true\n }\n ]\n}" let postData = parameters.data(using: .utf8) var request = URLRequest(url: URL(string: "{{apiPath}}/directory/v1/{{dn}}/subtree/search")!,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 200 OK ```json { "_links": { "self": { "href": "https://ds.example.com/directory/v1/ou=People,dc=example,dc=com/subtree/search", "data": { "limit": 100, "searchScope": "wholeSubtree", "filter": "uid eq \"user.68\"" } } }, "_embedded": { "entries": [ { "mail": [ "test@test.com", "abc@defg.com" ], "sn": [ "Karwowski" ], "cn": [ "Austin Karwowski" ], "description": [ "8b383262-eb69-43aa-9720-6e8e34796481", "973cf4d6-f871-4ea3-a64e-e26acc93e30d", "847c8ace-4ebc-4f0f-a408-4649e6f51d5b" ], "uid": [ "user.68" ], "isDirectMemberOf": [ "cn=Org-1,ou=Admins,dc=example,dc=com" ], "isMemberOf": [ "cn=Org-1,ou=Admins,dc=example,dc=com" ], "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ], "_dn": "uid=user.68,ou=People,dc=example,dc=com", "_links": { "schemas": [ { "href": "https://ds.example.com/directory/v1/schemas/inetOrgPerson" } ], "self": { "href": "https://ds.example.com/directory/v1/uid=user.68,ou=People,dc=example,dc=com" }, "isMemberOf": [ { "href": "https://ds.example.com/directory/v1/cn=Org-1,ou=Admins,dc=example,dc=com" } ], "isDirectMemberOf": [ { "href": "https://ds.example.com/directory/v1/cn=Org-1,ou=Admins,dc=example,dc=com" } ] }, "_controls": [ { "oid": "1.3.6.1.4.1.30221.2.5.9", "control-name": "Join Result Control", "criticality": false, "value-json": { "result-code": 0, "joined-entries": [ { "_dn": "uid=user.67,ou=People,dc=example,dc=com", "objectClass": [ "top", "person", "organizationalPerson", "inetOrgPerson" ], "mail": [ "user.67@example.com" ], "initials": [ "KHM" ], "homePhone": [ "+1 675 225 0395" ], "pager": [ "+1 041 404 4168" ], "givenName": [ "Kathlin" ], "employeeNumber": [ "67" ], "telephoneNumber": [ "+1 170 960 0090" ], "mobile": [ "+1 502 609 9004" ], "sn": [ "Mymryk" ], "cn": [ "Kathlin Mymryk" ], "description": [ "This is the description for Kathlin Mymryk." ], "street": [ "43172 Lee Street" ], "st": [ "SC" ], "postalAddress": [ "Kathlin Mymryk$43172 Lee Street$Baton Rouge, SC 73430" ], "uid": [ "user.67" ], "l": [ "Baton Rouge" ], "postalCode": [ "73430" ], "title": [ "TheDescriptionForKathlin" ], "manager": [ "uid=user.66,ou=People,dc=example,dc=com" ] } ] } } ] } ] }, "size": 1 } ```