---
title: "Publicv1Matterrouter.Sync Matter"
method: PUT
path: "/v1/matters/{external_matter_id}"
tags: ["v1"]
---

# Publicv1Matterrouter.Sync Matter

`PUT /v1/matters/{external_matter_id}`

## Request

- Base URL: `https://app.eve.legal` (the document declares no server; this is the origin it was published from)
- URL: `https://app.eve.legal/v1/matters/{external_matter_id}`
- Auth: OAuth 2
  - Password
  - Token URL: `token`

## Path parameters

- `external_matter_id` string, required

## Request body

- SyncMatterRequest
  - `name` string, required: Name of the matter
  - `associatedUsers` MatterUserRequest[], nullable: Users to include on the matter. Users that are not in the list lose their access and the team roles that the API gave them. If omitted, access and team roles do not change.
    - `email` string, required: Email of the user
    - `teamRoles` TeamRoleReference[], nullable: Team roles of the user on the matter. If any user in the request has teamRoles, the request sets the full team: users without teamRoles lose the roles that the API gave them. Eve creates a role that does not exist yet.
      - `externalId` string, required: Your ID of the team role
      - `name` string, required: Name of the team role. If the role exists with another name, Eve renames it.
  - `closed` boolean: Whether the matter is closed
  - `visibility` 'ORG' | 'USER'
  - `practiceArea` PracticeAreaReference: A practice area from your system.
    - `externalId` string, required: Your ID of the value
    - `name` string, required: Name of the value. If Eve has a value with the same name that is not linked to an ID, Eve links that value to your ID. Otherwise Eve creates the value.
  - `caseType` CaseTypeReference: A case type from your system, in the practice area of the same request.
    - `externalId` string, required: Your ID of the value
    - `name` string, required: Name of the value. If Eve has a value with the same name that is not linked to an ID, Eve links that value to your ID. Otherwise Eve creates the value.
  - `stage` StageReference: A stage from your system, in the practice area of the same request.
    - `externalId` string, required: Your ID of the value
    - `name` string, required: Name of the value. If Eve has a value with the same name that is not linked to an ID, Eve links that value to your ID. Otherwise Eve creates the value.
    - `enteredAt` string, date-time, nullable: Time when the matter entered the stage. Eve uses it only when the stage changes. If null, Eve uses the time of the request
  - `externalCreatedAt` string, date-time, nullable: Time when your system created the matter. Eve reads a value without a UTC offset as Pacific time (America/Los_Angeles) and stores UTC. Eve rejects a value on or before 1970-01-01 or more than one day in the future with 422. If null, Eve keeps the stored value.
  - `externalLastUpdatedAt` string, date-time, nullable: Time when your system last changed the matter. Eve reads a value without a UTC offset as Pacific time (America/Los_Angeles) and stores UTC. Eve rejects a value on or before 1970-01-01 or more than one day in the future with 422. If null, Eve keeps the stored value.

## Response `200`

Successful Response

- MatterResponse
  - `matter` Matter, required
    - `id` string, uuid, required: ID of the matter
    - `externalId` string, nullable, required: External ID of the matter
    - `name` string, required: Name of the matter
    - `associatedUsers` MatterUser[], required: Users associated with the matter
      - `email` string, required: Email of the user
      - `id` string, required: Eve ID of the user
      - `teamRoles` AssignedTeamRole[]: Team roles that the API gave the user on the matter. Roles assigned in the Eve app are not listed.
        - `id` string, uuid, required: Eve ID of the team role
        - `externalId` string, required: Your ID of the team role
        - `name` string, required: Name of the team role in Eve
    - `visibility` 'ORG' | 'USER', required
    - `closed` boolean, required: Whether the matter is closed
    - `createdAt` string, required: ISO timestamp of when the matter was created
    - `updatedAt` string, required: ISO timestamp of when the matter was last updated
    - `practiceArea` PracticeArea, required: Practice area of the matter.
      - `id` string, uuid, required: Eve ID of the value
      - `externalId` string, nullable, required: Your ID of the value, or null if the API did not set the value
      - `name` string, required: Name of the value in Eve
    - `caseType` CaseType, required: Case type of the matter.
      - `id` string, uuid, required: Eve ID of the value
      - `externalId` string, nullable, required: Your ID of the value, or null if the API did not set the value
      - `name` string, required: Name of the value in Eve
    - `stage` Stage, required: Stage of the matter.
      - `id` string, uuid, required: Eve ID of the value
      - `externalId` string, nullable, required: Your ID of the value, or null if the API did not set the value
      - `name` string, required: Name of the value in Eve
      - `enteredAt` string, nullable, required: ISO timestamp of when the matter entered the stage, or null if Eve has no stage history for it
  - `associatedUsersWarnings` AssociatedUserWarning[]: Users and team roles that the sync did not apply. The rest of the matter synced.
    - `email` string, required: Email of the user, as sent in the request
    - `externalRoleId` string, nullable, required: Your ID of the team role that Eve did not apply, or null when Eve did not apply the whole user
    - `reason` 'USER_NOT_FOUND' | 'USER_BLOCKED' | 'ROLE_ALREADY_ASSIGNED_IN_REQUEST', required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Validation Error

---

[API](https://skmtc.dev/eve/apis/eve-public-api.md) - [All operations](https://skmtc.dev/eve/apis/eve-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/eve/apis/eve-public-api/revisions/1a108b551ef3?raw)