Skip to content
/
Create a matter

LegalOn API (1.2.0)

API documentation for LegalOn services

Languages
Servers
The server URL is `{api_base_url}/rest/v1`. You can construct the server URL using the value of `api_base_url` provided in the response when obtaining an access token.
https://{api_base_url_without_scheme}/rest/v1

Users

Operations about user

Operations

User Groups

Operations about user group

Operations

Workspaces

Operations about all tenant workspaces/folders regardless of the user's access permissions.

Operations

Departments

Operations about department

Operations

Contracts(Files)

Operations to create, retrieve, update, and delete contracts. For operations that target a workspace, specify a workspace_id obtained via the common Workspaces endpoint (GET /workspaces).

Operations

Matters

Operations to create, retrieve, update, and delete matters. Matter operations require an API credential owned by a user with a Matter Management Pro license.

Operations

Search matters

Request

Overview

Searches matters with the same filters, sort order, and offset pagination as the LegalOn matter list.

Search conditions

All filters supported by the existing Matter search are exposed using public API resource names. For example, specify a workspace ID rather than an internal space or location ID.

Related API

Use the timeline endpoint to retrieve public or private messages for a matter.

Security
OAuth2ClientCredentials
Query
assignee_operatorstring

Operator for combining main and sub-assignee conditions.

Default "and"
Enum"and""or"
created_at_fromstring(date-time)

Inclusive lower bound for a matter's creation time. Specify an RFC 3339 date-time with a UTC offset. For example, use 2026-09-10T00:00:00+09:00 to start searching from midnight on 2026-09-10 in UTC+09:00. The API compares the instant represented by the value without adjusting the timezone.

created_at_relativestring(MatterRelativeDateFilter)[ 1 .. 1000 ] characters^(current,,(days|weeks|months|years)|anyFutur...

Relative matter creation time filter in the same comma-separated format as the LegalOn matter list.

Example: created_at_relative=next,2,weeks
created_at_tostring(date-time)

Exclusive upper bound for a matter's creation time. Specify an RFC 3339 date-time with a UTC offset. For example, use 2026-09-11T00:00:00+09:00 to include all of 2026-09-10 in UTC+09:00. The API compares the instant represented by the value without adjusting the timezone.

custom_attributesArray of strings(MatterCustomAttributeFilter)[ 1 .. 50 ] items

Custom attribute filters using definition and option IDs returned by GET /matters/custom-attribute-definitions, in the same repeated JSON-string format as the LegalOn matter list.

Example: custom_attributes={"id":"00000000-0000-0000-0000-000000000010","t":"number","v":"1,100"}&custom_attributes={"id":"00000000-0000-0000-0000-000000000011","t":"date","v":",,true,next,2,weeks"}
due_date_fromstring(date-time)

Inclusive lower bound for a matter's due date. Specify an RFC 3339 date-time with a UTC offset. Due dates are calendar dates in the tenant's timezone. For example, for a tenant in UTC+09:00, use 2026-09-10T00:00:00+09:00 to start searching from 2026-09-10. The API compares the instant represented by the value without adjusting the timezone.

due_date_relativestring(MatterRelativeDateFilter)[ 1 .. 1000 ] characters^(current,,(days|weeks|months|years)|anyFutur...

Relative due date filter in the same comma-separated format as the LegalOn matter list.

Example: due_date_relative=next,2,weeks
due_date_tostring(date-time)

Exclusive upper bound for a matter's due date. Specify an RFC 3339 date-time with a UTC offset. For example, for a tenant in UTC+09:00, use 2026-09-11T00:00:00+09:00 to include due dates through 2026-09-10. The API compares the instant represented by the value without adjusting the timezone.

include_unassigned_main_assigneeboolean

Includes matters without a main assignee.

Default false
include_unassigned_sub_assigneeboolean

Includes matters without sub-assignees.

Default false
last_message_at_fromstring(date-time)

Inclusive lower bound for the latest message time associated with a matter, not the matter's update time. Specify an RFC 3339 date-time with a UTC offset. For example, use 2026-09-10T00:00:00+09:00 to start searching from midnight on 2026-09-10 in UTC+09:00. The API compares the instant represented by the value without adjusting the timezone.

last_message_at_relativestring(MatterRelativeDateFilter)[ 1 .. 1000 ] characters^(current,,(days|weeks|months|years)|anyFutur...

Relative latest message time filter in the same comma-separated format as the LegalOn matter list.

Example: last_message_at_relative=next,2,weeks
last_message_at_tostring(date-time)

Exclusive upper bound for the latest message time associated with a matter, not the matter's update time. Specify an RFC 3339 date-time with a UTC offset. For example, use 2026-09-11T00:00:00+09:00 to include all of 2026-09-10 in UTC+09:00. The API compares the instant represented by the value without adjusting the timezone.

limitinteger[ 1 .. 100 ]

Maximum number of matters to return.

Default 50
main_assignee_idsArray of strings(uuid)non-empty

Main assignee user IDs returned by the Users API.

matter_numberstring[ 1 .. 255 ] characters

Matter number filter.

matter_typestring

Matter type filter.

Enum"other""legal_request""contract_review""contract_drafting"
offsetinteger>= 0

Number of matching matters to skip.

Default 0
qstring[ 1 .. 1000 ] characters

Full-text query for matters.

requester_idsArray of strings(uuid)non-empty

Requester IDs from requester.requester_id in Matter API responses. Both user and guest requester IDs are accepted and combined with OR. Matter creation and update identify a requester by email address and name, but search uses requester IDs because the existing Matter search supports ID filters only. A guest directory API is not provided.

requesting_department_idsArray of strings(uuid)non-empty

Requesting department IDs returned by the Departments API. A matter matches any specified department.

sortArray of strings

Sort expressions. If omitted, results are sorted by Matter ID in descending order.

Items Enum"created_at:asc""created_at:desc""due_date:asc""due_date:desc""last_message_at:asc""last_message_at:desc"
status_idsArray of strings(uuid)non-empty

Matter status IDs returned by GET /matters/statuses. A matter matches any specified status.

sub_assignee_idsArray of strings(uuid)non-empty

Sub-assignee user IDs returned by the Users API.

workspace_idstring(uuid)

Workspace ID returned by the Workspaces API. Specify the public workspace ID, not an internal space or location ID.

curl -i -X GET \
  'https://{api_base_url_without_scheme}/rest/v1/matters?assignee_operator=and&created_at_from=2019-08-24T14%3A15%3A22Z&created_at_relative=next%2C2%2Cweeks&created_at_to=2019-08-24T14%3A15%3A22Z&custom_attributes={%22id%22%3A%2200000000-0000-0000-0000-000000000010%22%2C%22t%22%3A%22number%22%2C%22v%22%3A%221%2C100%22}%2C{%22id%22%3A%2200000000-0000-0000-0000-000000000011%22%2C%22t%22%3A%22date%22%2C%22v%22%3A%22%2C%2Ctrue%2Cnext%2C2%2Cweeks%22}&due_date_from=2019-08-24T14%3A15%3A22Z&due_date_relative=next%2C2%2Cweeks&due_date_to=2019-08-24T14%3A15%3A22Z&include_unassigned_main_assignee=false&include_unassigned_sub_assignee=false&last_message_at_from=2019-08-24T14%3A15%3A22Z&last_message_at_relative=next%2C2%2Cweeks&last_message_at_to=2019-08-24T14%3A15%3A22Z&limit=50&main_assignee_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&matter_number=string&matter_type=other&offset=0&q=string&requester_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&requesting_department_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&sort=created_at%3Aasc&status_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&sub_assignee_ids=497f6eca-6276-4993-bfeb-53cbbbba6f08&workspace_id=497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
mattersArray of objects(Matter)required

Matching matters.

matters[].​matter_idstring(uuid)required

LegalOn-generated matter ID.

matters[].​matter_numberstringnon-emptyrequired

Matter number.

matters[].​titlestringnon-emptyrequired

Matter title.

matters[].​overviewstringnon-empty

Matter overview. Omitted when it is not set.

matters[].​matter_typestringrequired

Matter type.

Enum"other""legal_request""contract_review""contract_drafting"
matters[].​due_datestring(date-time)

Matter due date. Omitted when it is not set.

matters[].​statusobject(MatterStatus)required

Matter status.

matters[].​status.​status_idstring(uuid)required

LegalOn-generated status ID.

matters[].​status.​display_namestringnon-emptyrequired

Status name.

matters[].​assigneeobject(MainAssigneeReference)

Main assignee of the matter. Omitted when it is not set.

matters[].​secondary_assigneeArray of objects(UserReference)required

Secondary assignees of the matter.

matters[].​secondary_assignee[].​user_idstring(uuid)required

LegalOn-generated user ID.

matters[].​secondary_assignee[].​display_namestringnon-emptyrequired

User display name.

matters[].​requesterobject(RequesterReference)

User or guest resolved as the matter requester.

matters[].​requesting_departmentobject(DepartmentReference)

Department reference.

matters[].​custom_attributesArray of objects(MatterCustomAttribute)required

Custom attributes set on the matter.

matters[].​custom_attributes[].​custom_attribute_definitionobject(MatterCustomAttributeDefinition)required

Definition of a matter custom attribute.

matters[].​custom_attributes[].​custom_attribute_definition.​custom_attribute_definition_idstring(uuid)required

LegalOn-generated custom attribute definition ID.

matters[].​custom_attributes[].​custom_attribute_definition.​display_namestringnon-emptyrequired

Custom attribute display name.

matters[].​custom_attributes[].​custom_attribute_definition.​kindstringrequired

Value type of the custom attribute.

Enum"single_selection""multiple_selection""single_line_text""number""date"
matters[].​custom_attributes[].​custom_attribute_definition.​display_orderinteger>= 0required

Display order of the custom attribute.

matters[].​custom_attributes[].​custom_attribute_definition.​optionsArray of objects(MatterCustomAttributeOption)required

Selectable options. Empty for non-selection attributes.

matters[].​custom_attributes[].​custom_attribute_definition.​options[].​custom_attribute_option_idstring(uuid)required

LegalOn-generated custom attribute option ID.

matters[].​custom_attributes[].​custom_attribute_definition.​options[].​display_namestringnon-emptyrequired

Option display name.

matters[].​custom_attributes[].​custom_attribute_definition.​options[].​display_orderinteger>= 0required

Display order of the option.

matters[].​custom_attributes[].​option_idsArray of strings(uuid)

Selected option IDs for a selection attribute.

matters[].​custom_attributes[].​text_valuestringnon-empty

Value for a single-line text attribute.

matters[].​custom_attributes[].​number_valueinteger(int32)>= 0

Value for a number attribute.

matters[].​custom_attributes[].​date_valuestring(date-time)

Value for a date attribute.

matters[].​workspaceobject(WorkspaceReference)required

Workspace reference. Both fields are omitted and an empty object is returned when the credential owner cannot view the workspace.

matters[].​workspace.​workspace_idstring(uuid)

LegalOn-generated workspace ID.

matters[].​workspace.​display_namestringnon-empty

Workspace display name.

matters[].​created_atstring(date-time)required

Matter creation time.

matters[].​last_message_atstring(date-time)

Time of the latest message. Omitted when no message exists.

total_sizeinteger>= 0required

Total number of matching matters.

Response
application/json
{
  "matters": [
    { … }
  ],
  "total_size": 1
}

Create a matter

Request

Overview

Creates a matter and sets the requester, optionally sets the requesting department, status, assignees, custom attributes, and up to 10 newly uploaded files in one request.

Specified fields

Send each new file as binary content in a multipart file part. The API performs the storage upload internally; clients do not obtain an upload URL or provide a file path or object path. The requester is required and is resolved from an email address and name. LegalOn prefers an active user, then reuses or creates a guest. A user or guest ID cannot be specified directly.

Constraints

  • This is a single-matter API. Clients may call it repeatedly for migration, but cannot preserve a source system's creation time.
  • Each file must be 100 MiB or smaller, and the combined file size must not exceed 200 MiB.

Processing notes

  • If any file fails validation or upload, the request fails without creating the matter.
  • This operation does not support an idempotency key. If the response is lost after processing, check whether the matter was created before retrying because another matter and attachments may be created.
Security
OAuth2ClientCredentials
Bodymultipart/form-datarequired

Matter creation request.

titlestring[ 1 .. 200 ] charactersrequired

Matter title.

matter_typestringrequired

Matter type.

Enum"other""legal_request""contract_review""contract_drafting"
workspace_idstring(uuid)required

Workspace where the matter is created.

overviewstring[ 1 .. 4000 ] characters

Matter overview.

due_datestring(date-time)

Matter due date.

requesterobject(RequesterInput)required

Requester identified by email address and name. A user or guest ID cannot be specified directly.

requester.​emailstring(email)<= 254 charactersrequired

Requester email address. LegalOn resolves an active user first, then reuses or creates a guest.

requester.​namestring[ 1 .. 300 ] charactersrequired

Requester name. When an existing guest is reused, its name is updated to this value.

requesting_department_idstring(uuid)

Requesting department to set.

status_idstring(uuid)

Status to set. Omit to use the default status.

main_assignee_idstring(uuid)

Main assignee user ID.

sub_assignee_idsArray of strings(uuid)<= 30 itemsunique

Sub-assignee user IDs. The same user ID cannot be specified more than once.

custom_attributesArray of objects(MatterCustomAttributePatch)[ 1 .. 50 ] items

Custom attributes to set. Definitions not specified remain unset. The same definition ID cannot be specified more than once.

filesArray of strings(binary)<= 10 items

Newly uploaded binary files. Specify the form field at most 10 times. The filename and Content-Type are read from each multipart file part; separate metadata fields are not used. Storage paths are managed internally and are not accepted as request fields. Filenames must be 200 characters or fewer, include an extension, contain no line breaks, and must not start or end with a period. Supported extensions are .pdf, .doc, .docx, .xls, .xlsx, .csv, .ppt, .pptx, .eml, .msg, .png, .gif, .jpg, and .jpeg. The Content-Type must match the extension under the same media-type rules as POST /files.

curl -i -X POST \
  'https://{api_base_url_without_scheme}/rest/v1/matters' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'title=Review NDA' \
  -F matter_type=contract_review \
  -F workspace_id=00000000-0000-0000-0000-000000000003 \
  -F 'overview=Please review this NDA.' \
  -F 'requester[email]=requester@example.com' \
  -F 'requester[name]=Request User' \
  -F status_id=00000000-0000-0000-0000-000000000002 \
  -F main_assignee_id=00000000-0000-0000-0000-000000000004 \
  -F sub_assignee_ids=00000000-0000-0000-0000-000000000005 \
  -F 'custom_attributes[0][custom_attribute_definition_id]=00000000-0000-0000-0000-000000000010' \
  -F 'custom_attributes[0][text_value]=High priority' \
  -F 'files=<binary file content>'

Responses

Created

Bodyapplication/json
matter_idstring(uuid)required

LegalOn-generated matter ID.

Response
application/json
{
  "matter_id": "00000000-0000-0000-0000-000000000001"
}

Get a matter

Request

Retrieves the specified matter. Related files and timeline items are not included.

Security
OAuth2ClientCredentials
Path
matter_idstring(uuid)required

LegalOn-generated matter ID.

curl -i -X GET \
  'https://{api_base_url_without_scheme}/rest/v1/matters/{matter_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
matter_idstring(uuid)required

LegalOn-generated matter ID.

matter_numberstringnon-emptyrequired

Matter number.

titlestringnon-emptyrequired

Matter title.

overviewstringnon-empty

Matter overview. Omitted when it is not set.

matter_typestringrequired

Matter type.

Enum"other""legal_request""contract_review""contract_drafting"
due_datestring(date-time)

Matter due date. Omitted when it is not set.

statusobject(MatterStatus)required

Matter status.

status.​status_idstring(uuid)required

LegalOn-generated status ID.

status.​display_namestringnon-emptyrequired

Status name.

assigneeobject(MainAssigneeReference)

Main assignee of the matter. Omitted when it is not set.

secondary_assigneeArray of objects(UserReference)required

Secondary assignees of the matter.

secondary_assignee[].​user_idstring(uuid)required

LegalOn-generated user ID.

secondary_assignee[].​display_namestringnon-emptyrequired

User display name.

requesterobject(RequesterReference)

User or guest resolved as the matter requester.

requesting_departmentobject(DepartmentReference)

Department reference.

custom_attributesArray of objects(MatterCustomAttribute)required

Custom attributes set on the matter.

custom_attributes[].​custom_attribute_definitionobject(MatterCustomAttributeDefinition)required

Definition of a matter custom attribute.

custom_attributes[].​custom_attribute_definition.​custom_attribute_definition_idstring(uuid)required

LegalOn-generated custom attribute definition ID.

custom_attributes[].​custom_attribute_definition.​display_namestringnon-emptyrequired

Custom attribute display name.

custom_attributes[].​custom_attribute_definition.​kindstringrequired

Value type of the custom attribute.

Enum"single_selection""multiple_selection""single_line_text""number""date"
custom_attributes[].​custom_attribute_definition.​display_orderinteger>= 0required

Display order of the custom attribute.

custom_attributes[].​custom_attribute_definition.​optionsArray of objects(MatterCustomAttributeOption)required

Selectable options. Empty for non-selection attributes.

custom_attributes[].​custom_attribute_definition.​options[].​custom_attribute_option_idstring(uuid)required

LegalOn-generated custom attribute option ID.

custom_attributes[].​custom_attribute_definition.​options[].​display_namestringnon-emptyrequired

Option display name.

custom_attributes[].​custom_attribute_definition.​options[].​display_orderinteger>= 0required

Display order of the option.

custom_attributes[].​option_idsArray of strings(uuid)

Selected option IDs for a selection attribute.

custom_attributes[].​text_valuestringnon-empty

Value for a single-line text attribute.

custom_attributes[].​number_valueinteger(int32)>= 0

Value for a number attribute.

custom_attributes[].​date_valuestring(date-time)

Value for a date attribute.

workspaceobject(WorkspaceReference)required

Workspace reference. Both fields are omitted and an empty object is returned when the credential owner cannot view the workspace.

workspace.​workspace_idstring(uuid)

LegalOn-generated workspace ID.

workspace.​display_namestringnon-empty

Workspace display name.

created_atstring(date-time)required

Matter creation time.

last_message_atstring(date-time)

Time of the latest message. Omitted when no message exists.

Response
application/json
{
  "matter_id": "00000000-0000-0000-0000-000000000001",
  "matter_number": "MAT-0001",
  "title": "Review NDA",
  "overview": "Please review this NDA.",
  "matter_type": "contract_review",
  "status": {
    "status_id": "00000000-0000-0000-0000-000000000002",
    "display_name": "In progress"
  },
  "secondary_assignee": [],
  "custom_attributes": [],
  "workspace": {
    "workspace_id": "00000000-0000-0000-0000-000000000003",
    "display_name": "Legal"
  },
  "created_at": "2026-08-18T00:00:00Z",
  "last_message_at": "2026-08-18T00:00:00Z"
}

Files

Operations to create files for use by LegalOn resources.

Operations

Workspaces

Workspaces/folders are the common units used to store and organize resources such as contracts. This endpoint returns the workspaces/folders the calling user has access to, as a tree. For operations that target a workspace (e.g., the Contract API), specify the workspace_id obtained here. To manage workspaces across the tenant (creation, permissions, etc.), see the admin workspace operations (/spaces).

Operations