O365 eDiscovery
39 min
the microsoft graph apis for ediscovery provide functionality for organizations to automate repetitive tasks and integrate with their existing ediscovery tools to build repeatable workflows that might be required based on industry regulations you can use the ediscovery apis to help with your legal needs the microsoft graph apis for ediscovery are intended for the use of ediscovery operations for litigation, investigation, and regulatory requests asset setup for an app to get authorization and access to microsoft graph using the client credentials flow, you must follow these five steps register the app with microsoft entra id configure microsoft graph application permissions on the app request administrator consent request an access token call microsoft graph using the access token for a detailed steps for the token generation, please refer to the o365 ediscovery authentication link https //learn microsoft com/en us/graph/auth v2 service?context=graph%2fapi%2fbeta\&view=graph rest beta\&tabs=http capabilities this connector provides the following capabilities create ediscoveryholdpolicy get ediscoverycase list ediscoverycases list ediscoverycustodian list ediscoveryholdpolicies create review set add to review set export review set limitations apis under the /beta version in microsoft graph are subject to change configurations oauth 2 0 client credentials authenticates using oauth 2 0 client credentials configuration parameters parameter description type required url a url to the target host string required token url string required client id the client id string required client secret the client secret string required scope permission scopes for this action array optional verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions add to review set start the process of adding a collection from microsoft 365 services to a review set after the operation is created, you can get the status of the operation by retrieving the location parameter from the response headers endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/reviewsets/{{ediscoveryreviewsetid}}/addtoreviewset method post input argument name type required description ediscoverycaseid string required unique identifier ediscoveryreviewsetid string required unique identifier search object required parameter for add to review set id string required the id of the ediscovery search you'd like to add to the review set additionaldataoptions string optional the options for adding items to reviewset output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 202, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking=(self)", "content security policy" "default src 'self'" }, "reason" "accepted" } ] create ediscoveryholdpolicy this action creates a new ediscoveryholdpolicy object endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/legalholds method post input argument name type required description ediscoverycaseid string required unique identifier displayname string required name of the resource description string optional parameter for create ediscoveryholdpolicy usersources\@odata bind array optional response data @odata type string optional response data email string optional parameter for create ediscoveryholdpolicy sitesources\@odata bind array optional response data @odata type string optional response data site object optional parameter for create ediscoveryholdpolicy weburl string optional url endpoint for the request output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data isenabled boolean output field isenabled errors array error message if any description string output field description createddatetime string time value lastmodifieddatetime string time value status string status value id string unique identifier displayname string name of the resource createdby object output field createdby application object output field application user object output field user id string unique identifier displayname object name of the resource lastmodifiedby object output field lastmodifiedby application object output field application user object output field user id string unique identifier displayname object name of the resource example \[ { "status code" 201, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking", "content security policy" "img src 'self' data" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases('b0073 ", "isenabled" true, "errors" \[], "description" "created from graph api", "createddatetime" "2022 05 23t03 54 11 1z", "lastmodifieddatetime" "2022 05 23t03 54 11 1z", "status" "pending", "id" "b9758bbc ddbd 45e0 8484 3eb49cf1ded3", "displayname" "my legalhold with sources", "createdby" {}, "lastmodifiedby" {} } } ] create review sets this action creates a new ediscoveryreviewset object endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/reviewsets method post input argument name type required description ediscoverycaseid string required unique identifier @odata type string optional response data id string optional the review set unique identifier read only displayname string required the name of the review set createdby object optional parameter for create review sets @odata type string optional the user who created the review set read only createddatetime string optional the datetime when the review set was created the timestamp type represents date and time information using iso 8601 format and is always in utc time output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data displayname string name of the resource id string unique identifier createddatetime string time value createdby object output field createdby application object output field application user object output field user id string unique identifier displayname object name of the resource userprincipalname string name of the resource example \[ { "status code" 201, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking=(self)", "content security policy" "default src 'self'" }, "reason" "created", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases('b0073 ", "displayname" "my review set 2", "id" "887306f5 1eb4 4409 b18c ba47f4e3fa9b", "createddatetime" "2022 05 23t16 33 13 5126494z", "createdby" {} } } ] export review set this action initiates an export from a reviewset endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/reviewsets/{{ediscoveryreviewsetid}}/export method post input argument name type required description ediscoverycaseid string required unique identifier ediscoveryreviewsetid string required unique identifier outputname string required name of the export description string optional description of the export exportoptions string optional pecifies options that control the format of the export possible values are originalfiles, text, pdfreplacement, fileinfo, tags the fileinfo member is deprecated and has stopped returning data the summary and load file are always included exportstructure string optional options that control file structure and packaging of the export output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 202, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking=(self)", "content security policy" "default src 'self'" }, "reason" "accepted" } ] get ediscoverycase this action reads the properties and relationships of an ediscoverycase object endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}} method get input argument name type required description ediscoverycaseid string required unique identifier count boolean optional count value expand string optional parameter for get ediscoverycase filter string optional parameter for get ediscoverycase format string optional parameter for get ediscoverycase orderby string optional parameter for get ediscoverycase search string optional parameter for get ediscoverycase select string optional parameter for get ediscoverycase skip number optional parameter for get ediscoverycase top number optional parameter for get ediscoverycase output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data description string output field description lastmodifieddatetime string time value status string status value closeddatetime object time value externalid string unique identifier id string unique identifier displayname string name of the resource createddatetime string time value lastmodifiedby object output field lastmodifiedby closedby object output field closedby example \[ { "status code" 200, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking", "content security policy" "default src 'self'" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases/$entit ", "description" "", "lastmodifieddatetime" "2022 05 22t18 36 46 597z", "status" "active", "closeddatetime" null, "externalid" "324516", "id" "22aa2acd 7554 4330 9ba9 ce20014aaae4", "displayname" "contoso litigation 005", "createddatetime" "2022 05 22t18 36 46 597z", "lastmodifiedby" null, "closedby" null } } ] list ediscoverycases this action retrieves a list of ediscoverycase objects and their properties endpoint url /security/cases/ediscoverycases method get input argument name type required description count boolean optional count value expand string optional parameter for list ediscoverycases filter string optional parameter for list ediscoverycases format string optional parameter for list ediscoverycases orderby string optional parameter for list ediscoverycases search string optional parameter for list ediscoverycases select string optional parameter for list ediscoverycases skip number optional parameter for list ediscoverycases top number optional parameter for list ediscoverycases output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data value array value for the parameter description string output field description lastmodifieddatetime string time value status string status value closeddatetime object time value externalid string unique identifier id string unique identifier displayname string name of the resource createddatetime string time value lastmodifiedby object output field lastmodifiedby application object output field application user object output field user id object unique identifier displayname string name of the resource closedby object output field closedby application object output field application user object output field user id object unique identifier displayname string name of the resource example \[ { "status code" 200, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking", "content security policy" "img src 'self' data" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases", "@odata count" 22, "value" \[] } } ] list ediscoverycustodian get a list of the custodian objects and their properties endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/custodians method get input argument name type required description ediscoverycaseid string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data value array value for the parameter status string status value holdstatus string status value createddatetime string time value lastmodifieddatetime string time value releaseddatetime object time value id string unique identifier displayname string name of the resource email string output field email acknowledgeddatetime string time value example \[ { "status code" 200, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking", "content security policy" "img src 'self' data" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases('b0073 ", "@odata count" 1, "value" \[] } } ] list ediscoveryholdpolicies get a list of the ediscoveryholdpolicy objects and their properties for a case endpoint url /security/cases/ediscoverycases/{{ediscoverycaseid}}/legalholds method get input argument name type required description ediscoverycaseid string required unique identifier count boolean optional count value expand string optional parameter for list ediscoveryholdpolicies filter string optional parameter for list ediscoveryholdpolicies format string optional parameter for list ediscoveryholdpolicies orderby string optional parameter for list ediscoveryholdpolicies search string optional parameter for list ediscoveryholdpolicies select string optional parameter for list ediscoveryholdpolicies skip number optional parameter for list ediscoveryholdpolicies top number optional parameter for list ediscoveryholdpolicies output parameter type description status code number http status code of the response reason string response reason phrase @odata context string response data @odata count number response data value array value for the parameter isenabled boolean output field isenabled errors array error message if any contentquery string response content description object output field description createddatetime string time value lastmodifieddatetime string time value status string status value id string unique identifier displayname string name of the resource createdby object output field createdby application object output field application user object output field user id string unique identifier displayname object name of the resource lastmodifiedby object output field lastmodifiedby application object output field application user object output field user id string unique identifier displayname object name of the resource example \[ { "status code" 200, "response headers" { "date" "mon, 30 oct 2023 17 08 47 gmt", "content type" "application/json", "transfer encoding" "chunked", "connection" "keep alive", "vary" "origin, access control request method, access control request headers, origin, a ", "content encoding" "gzip", "expires" "0", "cache control" "no cache, no store, max age=0, must revalidate", "x xss protection" "1; mode=block, 1; mode=block", "pragma" "no cache", "x content type options" "nosniff, nosniff", "strict transport security" "max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; prelo ", "x frame options" "deny, deny", "permissions policy" "xr spatial tracking", "content security policy" "img src 'self' data" }, "reason" "ok", "json body" { "@odata context" "https //graph microsoft com/beta/$metadata#security/cases/ediscoverycases('b0073 ", "@odata count" 2, "value" \[] } } ] response headers header description example cache control directives for caching mechanisms no cache, no store, max age=0, must revalidate cf cache status http response header cf cache status dynamic cf ray http response header cf ray 81e54323fddf9a90 nag connection http response header connection keep alive content encoding http response header content encoding gzip content security policy http response header content security policy img src 'self' data content type the media type of the resource application/json date the date and time at which the message was originated mon, 30 oct 2023 17 08 47 gmt expires the date/time after which the response is considered stale 0 permissions policy http response header permissions policy xr spatial tracking=(self) pragma http response header pragma no cache referrer policy http response header referrer policy strict origin when cross origin server information about the software used by the origin server cloudflare strict transport security http response header strict transport security max age=31536000 ; includesubdomains, max age=63072000; includesubdomains; preload transfer encoding http response header transfer encoding chunked vary http response header vary origin, access control request method, access control request headers, origin, access control request method, access control request headers x content type options http response header x content type options nosniff, nosniff x frame options http response header x frame options deny, deny x xss protection http response header x xss protection 1; mode=block, 1; mode=block notes o365 ediscovery documentation link https //learn microsoft com/en us/graph/api/security ediscoverycase get?view=graph rest beta\&tabs=http o365 ediscovery authentication link https //learn microsoft com/en us/graph/auth v2 service?context=graph%2fapi%2fbeta\&view=graph rest beta\&tabs=http