Processing API services for REST

The Processing API provides HTTP services based on .NET interfaces. The Relativity REST API supports these services, which you can use to automate processing by following standard Representational State Transfer (REST) features. For more information, see REST API.

Similar to the .NET interfaces on the Processing API, you can use the following services supported through REST to automate your processing workflows:

Processing Custodian Manager
Processing Profile Manager
Processing Set Manager
Processing Data Source Manager
Processing Job Manager

All of these services support create, read, and update operations except for the Processing Job Manager, which supports running inventory, discovery, and publishing jobs. You use the SaveAsync request for create and update operations. Additionally, all of these operations run asynchronously.

Note: You must install the Processing application in your Relativity environment to automate processing workflows with the Processing API. For more information, see Installing and configuring Processing on the Relativity Documentation site.

This page contains the following information:

Client code sample
Custodians
Processing profiles
Processing data sources
Processing sets
Inventory jobs
Discovery jobs
Publishing jobs
Cancel jobs

See these related pages:

Client code sample

You can use the following .NET code as the REST client for performing any of the operations available in the Processing API. The code currently illustrates how to submit a discovery job, but you can modify it as follows to perform other operations:

Set the url variable to the URL for the operation that you want to perform.
Set the string represented by QueryInputJSON object to the JSON input required for your operation.

//Set up the client.
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost/");
  
//Set the required headers.
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", "Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=");
  
//Call the operation that you want to run.
string url = "Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitDiscoveryJobsAsync”;
StringContent content = new StringContent(QueryInputJSON);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Ok == response.StatusCode;
  
//Parse the result with Json.NET.
JObject resultObject = JObject.Parse(result);

Custodians

A custodian is a user who's associated with the data included in a processing job. For more information, see Entity object on the Relativity Documentation site.

Create or update a custodian

Use this URL on the Processing Custodian Manager service to create or update a custodian:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Custodian Manager/SaveAsync

You can send a request for a custodian who is an individual or an entity, such as corporation, data location, or other construct.

The request to create or update a custodian who is an individual must contains the following fields:

DocumentNumberingPrefix – the prefix applied to files when published through processing. For more information, see Processing sets on the Relativity Documentation site.
FirstName and LastName – the first and last name of the custodian.
CustodianType – indicates whether the custodian is an individual or an entity. It must be set to "Person" for an individual. Entity object on the Relativity Documentation site.
workspaceArtifactId – the Artifact ID of the workspace that contains the custodian.

{
   "Custodian":{
      "DocumentNumberingPrefix":"REL",
      "FirstName":"Custodian First Name",
      "LastName":"Custodian Last Name",
      "CustodianType":"Person"
   }, 
   "workspaceArtifactId":1093143
}

The request to create or update a custodian who is an entity contains the following fields:

DocumentNumberingPrefix – the prefix applied to files when published through processing. For more information, see Processing sets on the Relativity Documentation site.
Name – the value corresponding to that used in the Full Name field on a Custodian object in Relativity.
CustodianType – indicates whether the custodian is an individual or an entity. It must be set to "Entity" for a corporation, data location, or other construct.It must be set to "Other" for a corporation, data location, or other construct. For more information, see Entity object on the Relativity Documentation site.
workspaceArtifactId – the Artifact ID of the workspace that contains the custodian.

{
   "Custodian":{
      "DocumentNumberingPrefix":"relativity-",
      "Name":"Relativity ODA LLC",
      "CustodianType":"Entity"
   }, 
   "workspaceArtifactId":1093143
}

{
   "Custodian":{
      "DocumentNumberingPrefix":"relativity-",
      "Name":"Relativity ODA LLC",
      "CustodianType":"Other"
   }, 
   "workspaceArtifactId":1093143
}

The response returns the Artifact ID of the custodian that was created or updated, such as the integer 1060372.

Read a custodian

Use this URL on the Processing Custodian Manager service to retrieve a custodian:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Custodian Manager/ReadAsync

The request must include Artifact ID for the custodian and the workspace:

{
   "ArtifactId":1041433,
   "WorkspaceArtifactId":1093143
}

The response for custodian who is an individual contains the following fields:

DocumentNumberingPrefix – the prefix applied to files when published through processing. For more information, see Processing sets on the Relativity Documentation site.
FirstName and LastName – the first and last name of the custodian.
CustodianType – returns "Person" indicating that the custodian is an individual.
ArtifactId – the Artifact ID of the ProcessingCustodian object.
Name – the full name of the custodian.

{
"DocumentNumberingPrefix": "Laura-"
"FirstName": "Laura"
"LastName": "Libera"
"CustodianType": "Person"
"ArtifactID": 1038911
"Name": "Libera, Laura"
}

The response for custodian that is an entity contains the same fields as a custodian who is a person. However, the CustodianType fields contains "Entity", and "FirstName" and "LastName" don't contain any values.

{
  "DocumentNumberingPrefix": "relativity-"
  "FirstName": "-"
  "LastName": "-"
  "CustodianType": "Entity"
  "ArtifactID": 1038912
  "Name": "Relativity ODA LLC"
}

Processing profiles

A processing profile defines the settings that processing engine uses when it publishes documents associated with a specific processing set. These settings include those for handling numbering, deNISTing, extraction, and deduplication tasks. For more information, see Processing profiles on the Relativity Documentation site.

Create or update a processing profile

Use the SaveAsync endpoint to create or update a processing profile. Send a request to this URL on the Processing Profile Manager service:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/SaveAsync

View field descriptions for a processing profile request

{
   "processingProfileSaveRequest":{
      "ProcessingProfile":{
         "Name":"Modified Profile",
         "ArtifactId":1041094,
         "NumberingSettings":{
            "DefaultDocumentNumberingPrefix":"REL",
            "NumberingType":"DefineStartNumber",
            "DefaultStartNumber":4,
            "Delimiter":"Underscore",
            "NumberofDigits":"NumberofDigits4",
            "ParentChildNumbering":"SuffixAlways"
         },
         "InventoryDiscoverSettings":{
            "DeNIST":true,
            "DeNISTMode":"DoNotBreakParentChildGroups",
            "DefaultOCRlanguages":[
               "English"
            ],
            "DefaultTimeZoneID":1037890
         },
         "ExtractionSettings":{
            "Extractchildren":true,
            "ChildExtractionMethod":[
               "MSOfficeEmbeddedObjects",
               "EmailInlineImages"
            ],
            "ExcelTextExtractionMethod":"Native",
            "ExcelHeaderFooterExtraction":"ExtractAndPlaceAtEnd",
            "WordTextExtractionMethod":"Native",
            "PowerPointTextExtractionMethod":"Native",
            "OCR":true,
            "OCRAccuracy":"Medium",
            "OCRTextSeparator":true,
            "EmailOutput":"MHT"
         },
         "DeduplicationSettings":{
            "DeduplicationMethod":"Global",
            "PropagateDeduplicationData":true
         },
         "PublishSettings":{
            "UseSourceFolderStructure":false,
            "AutopublishSet":true,
            "DefaultDestinationFolder":{
               "ArtifactID":1003697
            }
         }
      },
      "WorkspaceId":1017155
   }
}

When a processing profile is successfully created or updated, the JSON response contains the ProcessingProfileId field, which is set to the Artifact ID of the profile.

{
   "ProcessingProfileId":1041094
}

Retrieve a processing profile

Use the ReadAsync endpoint to retrieve a processing profile. Send a request to this URL on the Processing Profile Manager service:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/ReadAsync

The request must contain a processingProfileReadRequest object with the following fields set:

ProcessingProfileId - the Artifact ID of the processing profile.
WorkspaceId - the Artifact ID of the workspace that contains the processing profile.

{
   "processingProfileReadRequest":{
      "ProcessingProfileId":1041093,
      "WorkspaceId":1017196
   }
}

The response contains the following fields:

Miscellaneous fields - the various fields set on a processing profile. For more information, see the field descriptions in Create or update a processing profile.
ArtifactID - the Artifact ID of the processing profile that you retrieved.
Name - the user-friendly name of the processing profile.
IsNew - returns true if the processing set is new.

{
   "ProcessingProfile":{
      "NumberingSettings":{
         "DefaultDocumentNumberingPrefix":"Mod",
         "NumberingType":"DefineStartNumber",
         "DefaultStartNumber":4,
         "Delimiter":"Underscore",
         "NumberOfDigits":"NumberOfDigits4",
         "ParentChildNumbering":"SuffixAlways"
      },
      "InventoryDiscoverSettings":{
         "DeNIST":true,
         "DeNISTMode":"DoNotBreakParentChildGroups",
         "DefaultOCRlanguages":[
            "English"
         ],
         "DefaultTimeZoneID":1037890
      },
      "ExtractionSettings":{
         "Extractchildren":true,
         "ChildExtractionMethod":[
            "MSOfficeEmbeddedObjects",
            "EmailInlineImages"
         ],
         "ExcelTextExtractionMethod":"Native",
         "ExcelHeaderFooterExtraction":"ExtractAndPlaceAtEnd",
         "WordTextExtractionMethod":"Native",
         "PowerPointTextExtractionMethod":"Native",
         "OCR":true,
         "OCRAccuracy":"Medium",
         "OCRTextSeparator":true,
         "EmailOutput":"MSG"
      },
      "DeduplicationSettings":{
         "DeduplicationMethod":"Global",
         "PropagateDeduplicationData":true
      },
      "PublishSettings":{
         "UseSourceFolderStructure":false,
         "AutopublishSet":true,
         "DefaultDestinationFolder":{
            "ArtifactID":1003697
         }
      },
      "ArtifactID":1041093,
      "Name":"REL Fest 7 - Final REL",
      "IsNew":false
   }
}

Delete a processing profile

Use the DeleteAsync endpoint to remove a processing profile from Relativity. Send a request to this URL on the Processing Profile Manager service:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/DeleteAsync

The request must contain a processingProfileDeleteRequest object with the following fields set:

ProcessingProfileId - the Artifact ID of the processing profile.
WorkspaceId - the Artifact ID of the workspace that contains the processing profile.

{
   "processingProfileDeleteRequest":{
      "ProcessingProfileId":1041026,
      "WorkspaceId":1017196
   }
}

The response contains the Deleted field, which is set to true when the processing profile is successfully removed from Relativity.

{
   "Deleted":true
}

Processing data sources

A data source contains the path used to specify the location of the files that you want to discover during processing. For more information, see Processing sets on the Relativity Documentation site.

Create or update a data source

Use this URL on the Processing Data Source Manager service to update or create a data source:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Data Source Manager/SaveAsync

The request must contain an InputPath field that specifies a file path, which the resource pool in the workspace can access. For more information, see Resource Pools on the Relativity Server2021 Documentation site.

It may also contain the StartNumber and IsStartNumberVisible properties. For more information, see Processing data sources.

{
   "processingDataSource": {
      "Custodian":1038885,
      "DestinationFolder":1003697,
      "DocumentNumberingPrefix":"REL",
      "InputPath":"\\\\localhost\\FileShare\\My Documents\\History of English.msg",
      "OcrLanguages":[
         "English"
      ],
      "Order":123,
      "ProcessingSet":{
         "ArtifactID":1038907
      },
      "TimeZone":1036905,
      "IsStartNumberVisible":true,
      "StartNumber":8,
      "ArtifactID":1038908,
      "Name":"1038908 - History of English"
   },
   "workspaceArtifactId":1378006
}

The response returns the Artifact ID of the data source that was created or updated, such as the integer 1046822.

Read a data source

Use this URL on the Processing Data Source Manager service to retrieve a data source:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Data Source Manager/ReadAsync

The request must include Artifact ID for the data source that you want to read, and the workspace where the data source resides:

{
   "ArtifactId":1038908,
   "workspaceArtifactId":1378006
}

The response for a read operation returns a JSON object with the following fields. The Name field for the processing set is always an empty string, while the Name field for the data source usually contains its Artifact ID.

{
  "Custodian": 1038885,
  "DestinationFolder": 1003697,
  "DocumentNumberingPrefix": "REL-",
  "InputPath": "\\localhost\FileShare\My Documents\History of English.msg",
  "IsNew": false,
  "OcrLanguages": [
    "English"
  ],
  "Order": 123,
  "ProcessingSet": {
    "ArtifactID": 1038907,
    "Name": ""
  },
  "TimeZone": 1036905,
  "StartNumber": 8,
  "IsStartNumberVisible": true,
  "ArtifactID": 1038908,
  "Name": "1038908 - History of English"
}

Validate deletion of a data source

You can use the ValidDeleteAsync endpoint to check if the specified processing data source is safe to be deleted. For example, if the processing set is already discovered or canceled. Use this URL on the Processing Data Source Manager service for deletion validation of the processing sets with the criteria specified in the JSON request:

<Host>/relativity.rest/api/Relativity.Processing.Services.IProcessingModule/workspace/{workspaceId}/processing-data-sources/{processingDataSourceId}/validate-delete

The request must include the following fields:

WorkspaceId – the Artifact ID of the workspace containing processing sets for deletion validation.
ProcessingDataSourceId – the Artifact ID of the processing data source.

The response includes the following fields:

CanDelete – returns true if the data source can be deleted.
Reasons – the reason(s) why the data source cannot be deleted. This will be empty if the data source is able to be deleted.

{
			"CanDelete": false,
			"Reasons": [
			"You can't delete the data source because the processing set has already been discovered."
			]
		}

Processing sets

A processing set object links a processing profile to one or more data sources. For more information, see Processing sets on the Relativity Documentation site.

Create or update a processing set

Use this URL on the Processing Set Manager service to create or update a processing set:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/SaveAsync

The request must include the Artifact ID for the workspace that contains the processing set, and the name and Artifact ID of the processing profile. You can also optionally include a list of recipients who receive email notifications after the creation or update of the processing set completes.

{
   "workspaceArtifactId":1093143,
   "ProcessingSet":{
      "EmailNotificationRecipients":[
         "jsmith@relativity.com",
         "bjones@relativity.com"
      ],
      "Name":"Processing Set  Name",
      "Profile":{
         "ArtifactID":1041350
      }
   }
}

The response returns the Artifact ID of the processing set that was created or updated, such as the integer 1046784.

Read a processing set

Use this URL on the Processing Set Manager service to retrieve a processing set:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/ReadAsync

The request must include Artifact ID for the processing set and the workspace that contains it:

{
   "artifactId":1045777,
   "workspaceArtifactId":1093143
}

The response includes the following fields. The Name field for the processing profile is always an empty string.

{
   "Profile":{
      "ArtifactID":1056549,
      "Name":"",
      "IsNew":false
   },
   "ArtifactID":1090382,
   "Name":"My Processing Set"
}

Retrieve aggregate information for processing sets

Use the GetDocumentAggregates endpoint to retrieve document aggregates and other information about processing sets with the status of Completed or Completed with errors in a specific workspace. For more information about the GetDocumentAggregates() method, see Retrieve a list of processing sets and related aggregate information.

Use this URL on the Processing Set Manager service to retrieve the processing sets with the criteria specified in the JSON request:

<host>/Relativity.Rest/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/GetDocumentAggregates

The request must include the following fields:

WorkspaceArtifactId – the Artifact ID of the workspace containing processing sets for retrieval.
PageSize – the number of processing sets returned per page in the results set. The Relativity UI uses this property to support paging and to display results. It determines the number of processing sets returned for each page.

In addition, the request may optionally include these fields:

Page – the number used to identify a specific page of processing sets that you want returned in the results set. This optional property is set to the first page (0) by default.
SortColumnName – the name of column used for sorting results. You can set the sort column property to one of the following options:
- "PublishedDocumentCount"
- "PublishedDocumentSizeInBytes"
- "ProcessingSetDateCreated"
- "ProcessingSetName" - name used by default.
SortDescending – indicates the sort order for the results. Set this property to true for descending order, and to false or null for ascending order. This optional property is set to ascending by default. When this property is null, it uses the ascending sort order based on sort column name.

{
    "request":{
        "WorkspaceArtifactId":1023139,
        "PageSize":15,
        "Page":0,
        "SortColumnName":"PublishedDocumentSizeInBytes",
        "SortDescending":true
    }
}

The response includes the following fields:

TotalPublishedDocuments – the total number of documents from all processing sets with the status of Completed or Complete with Errors published to a workspace.
TotalPublishedDocumentSizeInBytes – the total number of bytes for documents from all processing sets with the status of Completed or Complete with Errors published to a workspace.
TotalProcessingSets – the total number of processing sets with the status of Completed or Complete with Errors in a workspace.
ProcessingSetDocumentInfo – contains information about specific processing sets within a workspace. For additional reference information, see Processing API.

{
  "TotalPublishedDocuments": 15,
  "TotalPublishedDocumentSizeInBytes": 3563255,
  "TotalProcessingSets": 2,
  "ProcessingSetDocumentInfo": [
    {
      "ProcessingSetId": 1038688,
      "ProcessingSetName": "Test 1",
      "ProcessingSetDateCreated": "2016-06-02T19:25:42.547",
      "PublishedDocumentCount": 14,
      "PublishedDocumentSizeInBytes": 3531511
    },
    {
      "ProcessingSetId": 1042347,
      "ProcessingSetName": "Test 2",
      "ProcessingSetDateCreated": "2016-06-09T19:17:27.253",
      "PublishedDocumentCount": 1,
      "PublishedDocumentSizeInBytes": 31744
    }
  ]
}

Retrieve summary data for processing sets

Use the GetSummaryDataAsync endpoint to retrieve processing set summary data in a specific workspace to display to console, such as environment errors, discover and publish status, and more. For more information about the GetSummaryDataAsync() method, see Retrieve summary data of processing sets to display to console.

Use this URL on the Processing Set Manager service to retrieve the processing sets with the criteria specified in the JSON request:

<host>/Relativity.Rest/api/Relativity.Processing.Services.IProcessingModule/workspace/{workspaceId}/processing-sets/{processingSetId}/summary

The request must include the following fields:

WorkspaceId – the Artifact ID of the workspace containing processing sets for retrieval.
ProcessingSetId – the Artifact ID of the processing set.

The response includes the following fields:

SetState – the job status and other general information about the processing set.
- ArtifactId – the Artifact ID of the processing set.
- InventoryStatus – the inventory status GUID.
- DiscoverStatus – the discover status GUID.
- PublishStatus – the publish status GUID.
- Canceled – returns true if the job is canceled.
- ProcessingProfileId – the Artifact ID of the processing set's assigned processing profile.
HasRunningJobs – returns true if the processing set has any currently running jobs.
EnvironmentErrors – any environment errors that the processing set may have encountered in a workspace.
DataSourceIds – the data source Ids for the processing set.
DataSourceHasDocumentLevelErrors – returns true if the processing set has document level errors.
DataSourceHasJobLevelErrors – returns true if the processing set has job level errors.

{
    "SetState": {
        "ArtifactId": 1043783,
        "InventoryStatus": "4bab4cc3-a8a8-438c-a649-6fd4e0d111eb",
        "DiscoverStatus": "be180e9d-8abf-41f8-8507-37bd1d22f72e",
        "PublishStatus": "fc78eb19-b905-479c-9c3c-6fc49b95ea08",
        "Canceled": false,
        "ProcessingProfileId": 1040502
    },
    "HasRunningJobs": false,
    "EnvironmentErrors": [],
    "DataSourceIds": [
        1043784
    ],
    "DataSourceHasDocumentLevelErrors": false,
    "DataSourceHasJobLevelErrors": false
}

Inventory jobs

Use the SubmitInventoryJobsAsync endpoint to run an inventory job. Before you run a discovery job, you may want to exclude irrelevant raw files from your data set, such as eliminating NIST file types. You can perform this task by executing an inventory job. You can only run an inventory job on processing sets that haven't been discovered. If you want to apply filtering to your data, set your filters through the Relativity UI after the inventory job completes. For more information, see Inventory on the Relativity Documentation site.

Use this URL on the Processing Job Manager service to run an inventory job:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitInventoryJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "InventoryJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Discovery jobs

After you create a processing set and add a data source to it, you can initiate a discovery or processing job. During a job run, the processing engine discovers files in the data source based on the values specified in the processing set. For more information, see Processing on the Relativity Documentation site.

Use this URL on the Processing Job Manager service to run a discovery job:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitDiscoveryJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "DiscoveryJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Publishing jobs

Use the SubmitPublishJobsAsync endpoint to run publishing jobs. You can provide reviewers in Relativity with access to process data by publishing it to a workspace after it has been discovered. You must run a discovery job on the date before you can run a publishing job on it. For more information, see Publishing files on the Relativity Documentation site.

Use this URL on the Processing Job Manager service to run an publishing job:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitPublishJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "PublishJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Cancel jobs

You can use the SubmitCancelJobAsync endpoint to cancel inventory, discovery, and publishing jobs for a specific processing set. Use this URL on the Processing Job Manager service to cancel a job:

  <host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitCancelJobAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "CancelJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job is submitted successfully. However, this return value doesn't indicate that the job has been canceled. Multiple factors influence when a worker picks up a cancel job and how long the job takes to execute. For example, the amount of data and system state can affect this outcome.

Note: The submission of cancel job returns successfully when the job associated with a processing set has already been canceled.

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet
Share knowledge with the Relativity developer community.	Access tools and resources to build an application.	Review the most recent product release notes.	Create .NET Apps faster with NuGet.

Processing API services for REST

Client code sample

Custodians

Create or update a custodian

Read a custodian

Processing profiles

Create or update a processing profile

Retrieve a processing profile

Delete a processing profile

Processing data sources

Create or update a data source

Read a data source

Validate deletion of a data source

Processing sets

Create or update a processing set

Read a processing set

Retrieve aggregate information for processing sets

Retrieve summary data for processing sets

Inventory jobs

Discovery jobs

Publishing jobs

Cancel jobs

Additional Resources