

Last date modified: July 07 2025
Imaging API provides multiple HTTP services used for programmatically interacting with imaging profiles, sets, jobs, and other related components:
Sample use cases for the imaging services include:
You can also access the Imaging API services through .NET. For more information, see Imaging (.NET).
The Imaging API is now versioned in the Osier release. The content on this page illustrates how to use this new versioned API. However, you can continue to use the legacy Imaging API with the Osier release although you should consider implementing any new functionality with the versioned Imaging API. For legacy documentation, see Imaging API on the Relativity Server 2021 Developers site.
Review the following guidelines for working with these services.
The URLs for REST endpoints contain path parameters that you need to set before making a call:
For example, you can use the following URL to retrieve an imaging profile:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/{ImagingProfileID}
Set the path parameters as follows:
An imaging profile defines a set of options that you can use when imaging a group of documents. It may include options for controlling how spreadsheets, emails, or other document types are imaged, such as page orientation, or other specialized settings. For more information, see
The Imaging Profile Manager service supports create, read, update, and delete operations on imaging profiles.
To create a basic imaging profile that uses options available on basic imaging engine, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/basic
The request body must contain a request object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"request":
{
"Name": "Basic Profile",
"Keywords": "Basic Imaging Keywords",
"Notes": "Basic Imaging Notes",
"BasicOptions": {
"ImageOutputDpi": 299,
"BasicImageFormat": 1, //JPEG
"ImageSize": 4, //Custom,
"MaximumImageHeight": 2.0, //Optional
"MaximumImageWidth": 5.5 //Optional
}
}
}
When an imaging profile is successfully created, the response contains its Artifact ID.
1
{{ImagingProfileID}}
To create a native imaging profile that uses options available on the native imaging engine, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/native
The request body must contain a request object with the following fields unless specifically identified as optional:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
{
"request":
{
"Name": "Native Profile from Postman",
"Keywords": "Native Imaging Keywords",
"Notes": "Native Imaging Notes",
"BasicOptions": {
"ImageOutputDpi": 305,
"BasicImageFormat": 1, //JPEG
"ImageSize": 4, //Custom,
"MaximumImageHeight": 11.5, //Optional
"MaximumImageWidth": 12.1 //Optional
},
"NativeOptions": {
"ImageOutputDpi": 400,
"NativeImageFormat": 0, //TIFF
"RenderColorPagesToJpeg": true,
"DitheringAlgorithm": 7, //Threshold
"DitheringThreshold": 100,
"MaxPagesPerDoc": 1000 //Optional
//TimeZoneFieldOnDocument
//LastModifiedDateOnDocument
},
"SpreadsheetOptions": {
"PaperSizeOrientation": 1, //Letter8Point5X11
"PageOrder": 2, //OverThenDown
"PrintArea": 1, //IgnorePrintArea
"HideAndPagebreakAfterConsecutiveBlankRowCol": 56,
"ShowTrackChanges": true,
"IncludeRowAndColumnHeadings": 2, //No
"IncludeHeadersAndFooters": 2, //No
"IncludeComments": true,
"IncludeGridlines": 1, //Yes
"IncludeBorders": true,
"UnhideHiddenWorksheets": true,
"LimitToPages": 45, //Optional,
//"ZoomLevelPercentage": 101, //Optional, ignored when FitTo* is set
"FitToPagesWide": 200, //Optional
"FitToPagesTall": 201, //Optional
"Formatting": [1,2], //[AutoFitColumns, ClearFormattingInEmptyRows] (Optional)
"TextVisibility": [0,1] //[RemoveBackgroundFillColors, SetTextColorToBlack] (Optional)
},
"EmailOptions": {
"Orientation": 1, //Landscape
"ResizeImagesToFitPage": true,
"ResizeTablesToFitPage": true,
"SplitTablesToFitPageWidth": true,
"DownloadImagesFromInternet": true,
"ClearIndentations": true,
"DetectCharacterEncoding": true,
"DisplaySmtpAddresses": true,
"ShowMessageTypeInHeader": false
},
"WordProcessingOptions": {
"ShowTrackChanges": true,
"PageOrientation": 2, //Landscape
"Include": [0, 2] //[Comments, HiddenText] (Optional)
},
"PresentationOptions": {
"ShowSpeakerNotes": true,
"SlideOrientation": 2 //Landscape
},
"HtmlOptions": {
"RemoveNonBreakingSpaceCodes": true
},
"NativeTypes": [
{
"ArtifactID": 1036955,
"Name": "DBase III"
},
{
"ArtifactID": 1036956,
"Name": "DBase IV or V"
},
{
"ArtifactID": 1036957,
"Name": "Framework III"
}
],
"ApplicationFieldCodes": [
{
"ArtifactID": 1038657,
"Name": "Word Date"
},
{
"ArtifactID": 1038666,
"Name": "Excel Page"
}
]
}
}
When an imaging profile is successfully created, the response contains its Artifact ID.
1
{{ImagingProfileID}}
To retrieve an imaging profile, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/{ImagingProfileID}
The request body is empty.
The response for a read operation contains the many of the same fields as a request for a create operation. See the field descriptions in Create a native imaging profile.
The read response also contains these fields:
For more information, see
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
{
"ImagingMethod": "Native",
"BasicOptions": {
"ImageOutputDpi": 300,
"BasicImageFormat": "Tiff",
"ImageSize": "OriginalSetting"
},
"NativeOptions": {
"ImageOutputDpi": 300,
"NativeImageFormat": "Tiff",
"RenderColorPagesToJpeg": false,
"DitheringAlgorithm": "FloydAndSteinberg"
},
"SpreadsheetOptions": {
"PaperSizeOrientation": "OriginalSetting",
"PageOrder": "OriginalSetting",
"PrintArea": "IgnorePrintArea",
"HideAndPageBreakAfterConsecutiveBlankRowCol": 10,
"ShowTrackChanges": true,
"IncludeRowAndColumnHeadings": "OriginalSetting",
"IncludeHeadersAndFooters": "OriginalSetting",
"IncludeComments": true,
"IncludeGridlines": "Yes",
"IncludeBorders": true,
"UnhideHiddenWorksheets": true
},
"EmailOptions": {
"Orientation": "Portrait",
"ResizeImagesToFitPage": true,
"ResizeTablesToFitPage": true,
"SplitTablesToFitPageWidth": true,
"DownloadImagesFromInternet": true,
"ClearIndentations": false,
"DetectCharacterEncoding": true,
"DisplaySmtpAddresses": false,
"ShowMessageTypeInHeader": false
},
"WordProcessingOptions": {
"ShowTrackChanges": true,
"PageOrientation": "OriginalSetting"
},
"PresentationOptions": {
"ShowSpeakerNotes": true,
"SlideOrientation": "OriginalSetting"
},
"HtmlOptions": {
"RemoveNonBreakingSpaceCodes": false
},
"NativeTypes": [
{
"ArtifactID": 1035893,
"Name": "Smart DataBase"
},
{
"ArtifactID": 1035894,
"Name": "DBase III"
}
],
"ArtifactID": 1039439,
"Name": "Native Profile"
}
To update an imaging profile, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/{ImagingProfileID}
The request body must contain a request object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"request":
{
"Name": "Profile Testing",
"BasicOptions": {
"ImageOutputDpi": 300,
"BasicImageFormat": "Jpeg",
"ImageSize": "OriginalSetting"
},
"NativeOptions": {
"ImageOutputDpi": 600,
"NativeImageFormat": "Jpeg"
}
}
}
When an imaging profile is successfully updated, the response contains its Artifact ID.
1
{{ImagingProfileID}}
To delete an imaging profile, send a DELETE request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-profiles/{ImagingProfileID}
The request body is empty.
When the imaging profile is successfully deleted, the response returns the status code of 200.
To running an imaging job, you need to create an imaging set, which consists of an imaging profile and a search containing the documents to image. For general information, see
The Imaging Sets Manager API supports create, read, update, and delete operations on imaging sets. It also supports the hide and release operations used for a QC Review of imaged documents.
To create an imaging set, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets
The request must contain the following fields:
1
2
3
4
5
6
7
8
{
"request" : {
"DataSourceID" : {{DataSourceID}},
"ImagingProfileID" : {{ImagingProfileID}},
"Name" : "All documents",
"EmailNotificationRecipients" : "some_person@test.com;some_other_person@test.com"
}
}
When an imaging set is successfully created, the response contains its Artifact ID.
1
{{ImagingSetID}}
To retrieve an imaging set, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}
The request body is empty.
The response returns the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"ImagingProfile": {
"ArtifactID": {{ImagingProfileID}}
},
"DataSourceID": {{DataSourceID}},
"Status": {
"LastRunError": "",
"QCEnabledOnLastRun": false,
"Status": "Completed with errors"
},
"ArtifactID": {{ImagingSetID}},
"Name": "All documents"
}
To update an imaging set, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}
The request for an update operation must contains the same fields as those for a create request. See the field descriptions for the request in Create an imaging set.
1
2
3
4
5
6
7
8
{
"request" : {
"DataSourceID" : {{DataSourceID}},
"ImagingProfileID" : {{ImagingProfileID}},
"Name" : "All documents",
"EmailNotificationRecipients" : "some_person@test.com;some_other_person@test.com"
}
}
When an imaging set is successfully updated, the response contains its Artifact ID.
1
{{ImagingSetID}}
To delete an imaging set, send a DELETE request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}
The request body is empty.
The response returns the status code of 200 when the image set is successfully deleted.
You can prevent users from viewing images that need to undergo a quality control review by hiding them. For more information, see
To hide an imaging set, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}/hide-images
The request body is empty.
When the image set is successfully hidden, the response returns the status code of 200.
After a quality control review has been completed on hidden images, you can make them available to reviewers by releasing them. Send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}/release-images
The request body is empty.
When the image set is successfully released, the response returns the status code of 200.
To retrieve the status of an imaging set, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}/status
When you read an imaging set, its status is also returned. See Retrieve an image set.
The request body is empty.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"Status": "Completed with errors",
"LastRunError": "",
"QcReviewEnabledOnLastRun": false,
"JobType": 0,
"NumberOfDocuments": 10,
"NumberOfDocumentsHidden": 0,
"NumberOfDocumentsViewable": 8,
"NumberOfDocumentsWithWarnings": 0,
"JobStatus": "Default",
"JobExists": false,
"NumberOfDocumentsCompleted": 0,
"NumberOfDocumentsSkipped": 8,
"NumberOfDocumentsWaiting": 0,
"NumberOfDocumentsErrored": 2,
"NumberOfDocumentsSubmitted": 0
}
You can retrieve native file types supported by Relativity for imaging. For more information, see
To retrieve a native type, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/native-types/{NativeTypeID}
The request body is empty.
The response returns the following fields:
1
2
3
4
5
6
7
8
9
{
"BasicCategory": "WordProcessor",
"UseNativeImaging": false,
"RestrictedFromImagingByDefault": false,
"FileTypeID": 1000,
"PreventNativeDownload": false,
"ArtifactID": 1036768,
"Name": "Word for DOS 4.x"
}
Microsoft applications use fields codes as placeholders for data that may be updated or used for other specialized purposes in their documents, such as those created in Word, Excel, or others. In Relativity, application field codes indicate how to handle field codes used in Microsoft documents during imaging. For more information, see
Use the Application Field Code Manager service to create, read, update, or delete application field codes.
To create an application field code, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/application-field-codes
The request must contain the following fields:
1
2
3
4
5
6
7
{
"ApplicationFieldCode": {
"FieldCode": "DateTime",
"Application": "MicrosoftWord",
"Option": "ShowFieldCode"
}
}
The response contains Artifact ID of the new field code.
1
{{applicationFieldCodeID}}
To retrieve an application field code, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/application-field-codes/{applicationFieldCodeID}
The request body is empty.
The response returns the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
{
"FieldCode": "Date",
"Application": "MicrosoftWord",
"Option": "ShowNothing",
"ImagingProfiles": [
{
"ArtifactID": 1037523
}
],
"ArtifactID": 1038657,
"Name": "MicrosoftWord Date ShowNothing"
}
To update an application field code, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/application-field-codes/{applicationFieldCodeID}
The request for an update operation must contains the same fields as those for a create request. See the field descriptions for the request in Create an application field code.
1
2
3
4
5
6
7
{
"ApplicationFieldCode": {
"FieldCode": "DateTime",
"Application": "MicrosoftExcel",
"Option": "ShowFieldCode"
}
}
The response contains Artifact ID of the updated field code.
1
{{applicationFieldCodeID}}
To delete an application field code, send a DELETE request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/application-field-codes/{applicationFieldCodeID}
The request body is empty.
When the application field code is successfully deleted, the response returns true.
1
true
Use the Imaging Job Manager service to run jobs to image documents, cancel a job currently executing on an imaging set, or retry errors that occurred during a job. For general information, see
To schedule an imaging set job, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}/run
The request body may contain the following field:
1
2
3
4
5
{
"imagingSetRequest":{
"QcEnabled":true
}
}
The response contains Artifact ID for the job.
1
2
3
{
"ImagingJobID": {{ImagingJobID}}
}
You can submit an imaging job for a single document, such as an image on the fly request. Send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/api/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/documents/{DocumentArtifactID}/image
The request body must contain the following fields:
1
2
3
4
5
{
"imageOnTheFlyRequest":{
"ProfileID":1036462
}
}
The response contains Artifact ID for the job.
1
2
3
{
"ImagingJobID": {{ImagingJobID}}
}
To submit a mass imaging job, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/documents/mass-image
The request body must contain the following fields:
1
2
3
4
5
6
7
{
"MassImageRequest":{
"ProfileId":"1036462",
"MassProcessId":5,
"sourceType":"0"
}
}
The response contains Artifact ID for the job.
1
2
3
{
"ImagingJobID": {{ImagingJobID}}
}
You can stop an in-progress imaging job, including jobs for imaging sets and image on the fly. Send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/jobs/{ImagingJobID}/stop
The request body must contain an empty JSON object as follows:
1
2
3
4
5
{
"stopImagingJobRequest":{
}
}
The response contains the following fields:
1
2
3
4
{
"Success": true,
"ErrorMessage": ""
}
To retry imaging set errors, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/imaging-sets/{ImagingSetID}/retry-errors
The request body must contain an empty JSON object as follows:
1
2
3
4
5
{
"imagingSetRequest":{
}
}
The response contains Artifact ID for the job.
1
2
3
{
"ImagingJobID": {{ImagingJobID}}
}
To update the priority of an imaging job, send a POST request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/jobs/{ImagingJobID}/priority
The request body must contain the following field:
1
2
3
4
5
{
"updateJobPriorityRequest":{
"Priority":1
}
}
The response contains the following fields:
1
2
3
4
{
"Success": true,
"ErrorMessage": ""
}
Use the Document Status Manager service to obtain status information about the imaging job for a document.
To retrieve the imaging status of a document, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/workspaces/{WorkspaceID}/documents/{DocumentArtifactID}/status
The request body is empty.
The response is a Document Image Status Response object that contains the following fields:
1
2
3
4
5
6
7
8
9
{
"ImageCount": 0,
"Error": {
"Message": "OI EXOpenExport failed - 11: file is password protected or encrypted [11]",
"Status": "ReadyToRetry"
},
"Warnings": [],
"HasImages": "Error"
}
Use the endpoints on the Imaging Environment Manager service to remove inactive jobs and to obtain the size of mass imaging jobs.
To remove inactive imaging jobs, send a DELETE request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/environment/jobs/inactive-jobs
The request body is empty.
When the inactive jobs are successfully deleted, the response returns the status code of 200.
To retrieve the size of a mass imaging job, send a GET request with a URL in the following format:
1
<host>/Relativity.Rest/API/relativity-imaging/{versionNumber}/environment/jobs/mass-imaging-max-size
The request body is empty.
The response contains an integer indicating the number of documents in the imaging job.
1
10000
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |