Skip to content
/
Create a matter message

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

List timeline items

Request

Overview

Retrieves paginated timeline items for the specified matter. The initial supported event type is message, and public messages are returned by default. The response uses an event envelope so additional event types can be added without changing the top-level timeline item structure.

Specified fields

Use the page_token, visibility, and page_size query parameters to control the retrieval scope and pagination. See the parameter descriptions for details.

Constraints

  • Returns 404 when the matter does not exist and 403 when the caller cannot view the existing matter.
  • Attachment metadata is not included in the response.

Processing notes

Private messages can contain sensitive information. When requesting private or all messages, ensure that external storage and forwarding preserve appropriate access controls and do not unintentionally share the content.

Related API

Use POST /matters/{matter_id}/messages to create a message.

Security
OAuth2ClientCredentials
Path
matter_idstring(uuid)required

LegalOn-generated matter ID.

Query
visibilitystring(MessageVisibilityFilter)

Message visibility to retrieve. The default is public.

Default "public"
Enum"public""private""all"
page_sizeinteger[ 1 .. 100 ]

Number of timeline items to return per page.

Default 50
page_tokenstring[ 1 .. 4096 ] characters

Opaque token for retrieving the previous or next page.

curl -i -X GET \
  'https://{api_base_url_without_scheme}/rest/v1/matters/{matter_id}/timeline-items?visibility=public&page_size=50&page_token=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
timeline_itemsArray of objects(TimelineItem)required

Timeline items matching the requested visibility.

timeline_items[].​event_typestring(TimelineEventType)required

Public timeline event type. Additional event types can be added without changing the TimelineItem envelope.

Value"message"
timeline_items[].​eventobject(TimelineItemEvent)= 1 propertyrequired

Event-specific timeline payload. The payload property corresponding to event_type is populated. The initial event type uses message.

timeline_items[].​event.​messageobject(MessageTimelineEvent)

Public payload for a message timeline item. Content, author, and is_edited are present for an active message and omitted when the message has been deleted. Attachment metadata is not returned by this API.

total_sizeinteger>= 0required

Total number of matching timeline items.

next_page_tokenstring[ 1 .. 4096 ] characters

Token for retrieving the next page. Omitted when there is no next page.

prev_page_tokenstring[ 1 .. 4096 ] characters

Token for retrieving the previous page. Omitted when there is no previous page.

Response
application/json
{
  "timeline_items": [
    { … }
  ],
  "total_size": 1,
  "next_page_token": "eyJjYXNlX3RpbWVsaW5lX2V2ZW50X2lkIjoiMDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDMwIiwidHlwZSI6Im5leHQifQ"
}

Create a matter message

Request

Overview

Creates a public or private message in the specified matter and optionally attaches up to 10 newly uploaded files.

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.

Constraints

  • Each file must be 100 MiB or smaller, and the combined file size must not exceed 200 MiB.
  • If any file fails validation or upload, the request fails without creating the message.

Processing notes

  • Private messages can contain sensitive information. Ensure that any external copy preserves appropriate access controls.
  • This operation does not support an idempotency key. If the response is lost after processing, check whether the message was created before retrying because another message and attachments may be created.
Security
OAuth2ClientCredentials
Path
matter_idstring(uuid)required

LegalOn-generated matter ID.

Bodymultipart/form-datarequired

Matter message creation request.

contentobject(MessageContent)required

Structured message content. Blocks are displayed in order as paragraphs. The total number of characters across all text and mention user IDs must be between 1 and 4000.

content.​blocksArray of objects(MessageContentBlock)non-emptyrequired

Ordered paragraph blocks. An empty inlines array represents a blank line.

content.​blocks[].​inlinesArray of objects(MessageContentInline)required

Ordered inline content in this paragraph. Specify an empty array to represent a blank line.

content.​blocks[].​inlines[].​typestringrequired

Inline content type.

Enum"text""mention"
content.​blocks[].​inlines[].​textstring[ 1 .. 4000 ] characters

Text to display. Required when type is text and omitted when type is mention.

content.​blocks[].​inlines[].​user_idstring(uuid)

LegalOn-generated ID of the user to mention. Required when type is mention and omitted when type is text.

content.​blocks[].​inlines[].​marksArray of strings(MessageInlineMarks)<= 3 itemsunique

Text decorations applied to the inline content. Omitted when no decoration is applied. The order has no meaning.

Items Enum"bold""strikethrough""underline"
visibilitystring(MessageVisibility)required

Visibility assigned to a message. Specify public or private.

Enum"public""private"
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/{matter_id}/messages' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'content[blocks][0][inlines][0][type]=text' \
  -F 'content[blocks][0][inlines][0][text]=Please review ' \
  -F 'content[blocks][0][inlines][1][type]=mention' \
  -F 'content[blocks][0][inlines][1][user_id]=00000000-0000-0000-0000-000000000001' \
  -F 'content[blocks][0][inlines][1][marks]=bold' \
  -F 'content[blocks][0][inlines][2][type]=text' \
  -F 'content[blocks][0][inlines][2][text]=the latest revision.' \
  -F 'content[blocks][0][inlines][2][marks]=bold' \
  -F 'content[blocks][0][inlines][2][marks]=underline' \
  -F 'content[blocks][2][inlines][0][type]=text' \
  -F 'content[blocks][2][inlines][0][text]=Comments are welcome.' \
  -F visibility=public \
  -F 'files=<binary file content>'

Responses

Created

Bodyapplication/json
message_idstring(uuid)required

LegalOn-generated message ID.

Response
application/json
{
  "message_id": "00000000-0000-0000-0000-000000000030"
}

Update a matter message

Request

Only the original author can update the content of the specified matter message. Returns 403 for another user and 404 when the message does not exist, belongs to another matter, or has already been deleted.

Security
OAuth2ClientCredentials
Path
matter_idstring(uuid)required

LegalOn-generated matter ID that owns the message.

message_idstring(uuid)required

LegalOn-generated message ID.

Bodyapplication/jsonrequired

Matter message content update request.

contentobject(MessageContent)required

Structured message content. Blocks are displayed in order as paragraphs. The total number of characters across all text and mention user IDs must be between 1 and 4000.

content.​blocksArray of objects(MessageContentBlock)non-emptyrequired

Ordered paragraph blocks. An empty inlines array represents a blank line.

content.​blocks[].​inlinesArray of objects(MessageContentInline)required

Ordered inline content in this paragraph. Specify an empty array to represent a blank line.

content.​blocks[].​inlines[].​typestringrequired

Inline content type.

Enum"text""mention"
content.​blocks[].​inlines[].​textstring[ 1 .. 4000 ] characters

Text to display. Required when type is text and omitted when type is mention.

content.​blocks[].​inlines[].​user_idstring(uuid)

LegalOn-generated ID of the user to mention. Required when type is mention and omitted when type is text.

content.​blocks[].​inlines[].​marksArray of strings(MessageInlineMarks)<= 3 itemsunique

Text decorations applied to the inline content. Omitted when no decoration is applied. The order has no meaning.

Items Enum"bold""strikethrough""underline"
curl -i -X PATCH \
  'https://{api_base_url_without_scheme}/rest/v1/matters/{matter_id}/messages/{message_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": {
      "blocks": [
        {
          "inlines": [
            {
              "type": "text",
              "text": "Please review the revised draft with ",
              "marks": [
                "underline"
              ]
            },
            {
              "type": "mention",
              "user_id": "00000000-0000-0000-0000-000000000001"
            }
          ]
        }
      ]
    }
  }'

Responses

No Content

Response
No content

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