Matter

Relativity REST API supports operations with the Matter objects though the Matter Manager service. The operations available through the service are equivalent to the asynchronous methods for interacting with the Matter objects in the Relativity Services API. For more information, see Matter in the Services API documentation.

Note: You can only use the POST method when interacting with the service.

This page contains the following information:

• Client code sample
• Create
• Read
• Update
• Delete
• Query
• Get clients
• Get status choices

Client code sample

The following is an example of .NET REST code for creating a Matter. The code can be used for all Matter Manager service operations with different endpoint URLs and input JSON values.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
//Set up the REST 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 c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

//Call Create for a Matter.
            
string url = "Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/CreateSingleAsync";
StringContent content = new StringContent(CreateInputJSON, Encoding.UTF8, "application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Created == response.StatusCode;

//Parse the result with Json.NET.
            
JObject resultObject = JObject.Parse(result);

Create

Use this Matter Manager service URL to create a Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/CreateSingleAsync

The request must include a valid JSON representation of a Matter DTO. The required properties include Name, Number, Status, and Client.

Note: You can only use the ArtifactID of the Choice to set the Matter status value.

Sample JSON request for creating a Matter

Copy

1
2
3
4
5
6
7
8
9
10
11
12
{
  "matterDTO": {
    "Name": "Tuchman vs Marsh",
    "Number": "123456789",
    "Status": {
      "ArtifactID": 671
    },
    "Client": {
      "ArtifactID": 13761026
    }
  }
}

The response is an ArtifactID of the created Matter.

Read

Use this Matter Manager service URL to read a Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/ReadSingleAsync

The request must include the Matter ArtifactID.

1
2
3
{
  "matterArtifactID": 13759952
}

The response returns a JSON representation of a Matter DTO.

Click to display JSON response

Copy

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
{
  "Number": "123456789",
  "Client": {
    "ArtifactID": 13761026,
    "Name": "Tuchman"
  },
  "Status": {
    "ArtifactID": 671,
    "Name": "Active",
    "Guids": null
  },
  "SystemCreatedBy": {
    "ArtifactID": 9,
    "Name": "Admin, Relativity"
  },
  "SystemCreatedOn": "2014-12-19T22:15:45.99",
  "SystemLastModifiedBy": {
    "ArtifactID": 9,
    "Name": "Admin, Relativity"
  },
  "SystemLastModifiedOn": "2014-12-19T22:15:45.99",
  "Keywords": "",
  "Notes": "",
  "ArtifactID": 13761061,
  "Name": "Tuchman vs Marsh"
}

Update

Use this Matter Manager service URL to update a Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/UpdateSingleAsync

The request must include a valid JSON representation of a Matter DTO.

Note: You must include all DTO field information in the update. You cannot update individual fields because fields left empty will be cleared on the update. All DTO fields are required except for system/user created by/created on.

The following JSON sample illustrates how to change the Name and Number properties of the Matter created in a previous example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "matterDTO": {
    "Number": "No12345PE",
    "Status": {
      "ArtifactID": 671,
      "Name": "Active",
      "Guids": null
    },
    "Keywords": "",
    "Notes": "",
    "ArtifactID": 13761061,
    "Name": "Tuchman vs Marsh - archived"
  }
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Delete

Use this Matter Manager service URL to delete a Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/DeleteSingleAsync

The request must include the Matter ArtifactID.

1
2
3
{
  "clientArtifactID": 13761061
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Query

The Matter Manager service URL for querying Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/QueryAsync

The request must include the query and optionally the number of results to return as the length property. The following is an example of a query for Matter objects with the name starting with "T". The result set is sorted by ArtifactID in descending order.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "query": {
    "Condition": "'Name' STARTSWITH 'T'",
    "Sorts": [
      {
        "FieldIdentifier": {
          "Name": "ArtifactID"
        },
        "Order": 0,
        "Direction": 1
      }
    ]
  },
  "length": 5
}

If more results are available than initially specified in the length property, the query returns a token value that is not null. The results can subsequently be retrieved by a call to the QuerySubsetAsync operation.

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/QuerySubsetAsync

Note that the QuerySubsetAsync request can specify the starting index of the result subset and the number of results to be returned.

1
2
3
4
5
{
  "queryToken": "a5079c32-e080-473d-846e-941ef6a5f086",
  "start": 6,
  "length": 5
}

To return all Clients in a Relativity instance, specify an empty Condition as shown in the JSON example below. When the length parameter is not specified, its value defaults to 0, and the number of returned results defaults to the Instance setting table value of PDVDefaultQueryCacheSize of 10000. For more information, see Search Relativity.

1
2
3
4

{
  "query":{}
}

The response returns a collection of Matter objects as a ClientQueryResultSet object.

Click to display JSON response

Copy

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
{
  "QueryToken": "7334c4af-e2ea-4061-873d-c403c7f7b96c",
  "TotalCount": 7,
  "Success": true,
  "Message": "",
  "Results": [
    {
      "Success": true,
      "Artifact": {
        "Number": "123456789",
        "Client": {
          "ArtifactID": 13761026,
          "Name": "API Sample 950861b5-4481-4406-896d-d9443bf1d06c"
        },
        "Status": {
          "ArtifactID": 671,
          "Name": "Active",
          "Guids": null
        },
        "SystemCreatedBy": {
          "ArtifactID": 9,
          "Name": "Admin, Relativity"
        },
        "SystemCreatedOn": "2014-12-19T22:15:45.99",
        "SystemLastModifiedBy": {
          "ArtifactID": 9,
          "Name": "Admin, Relativity"
        },
        "SystemLastModifiedOn": "2014-12-19T22:25:03.633",
        "Keywords": "",
        "Notes": "",
        "ArtifactID": 13761061,
        "Name": "Turner Case"
      },
      "Message": "",
      "WarningMessages": []
    },
    {
      "Success": true,
      "Artifact": {
        "Number": "TSA1234",
        "Client": {
          "ArtifactID": 13759827,
          "Name": "API Sample 53e93276-0010-4b97-8b05-f4b573fa1088"
        },
        "Status": {
          "ArtifactID": 671,
          "Name": "Active",
          "Guids": null
        },
        "SystemCreatedBy": {
          "ArtifactID": 9,
          "Name": "Admin, Relativity"
        },
        "SystemCreatedOn": "2014-12-19T21:43:21.907",
        "SystemLastModifiedBy": {
          "ArtifactID": 9,
          "Name": "Admin, Relativity"
        },
        "SystemLastModifiedOn": "2014-12-19T21:43:21.907",
        "Keywords": "",
        "Notes": "",
        "ArtifactID": 13761060,
        "Name": "Tuchman and Marsh"
      },
      "Message": "",
      "WarningMessages": []
    } ...
  ]
}

Get clients

Use this Matter Manager service URL for return the available clients that can be associated with the Matter:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/GetClientsForMatterAsync

The request does not include any parameters.

The response returns a collection of Client objects.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[
  {
    "ArtifactID": 13759847,
    "Name": "Tuchman and Marsh"
  },
  {
    "ArtifactID": 13759869,
    "Name": "DigitalDreams GmbH"
  },
  {
    "ArtifactID": 13758842,
    "Name": "Sample Client"
  }
]

Get status choices

Use this Matter Manager service URL for return the choices for the Matter status field:

1
<host>/Relativity.REST/api/Relativity.Services.Matter.IMatterModule/Matter%20Manager/GetStatusChoicesForMatterAsync

The request does not include any parameters.

The response is a collection of Choice objects.

1
2
3
4
5
6
7
8
9
10
11
12
[
  {
    "ArtifactID": 671,
    "Name": "Active",
    "Guids": []
  },
  {
    "ArtifactID": 670,
    "Name": "Inactive",
    "Guids": []
  }
]