> This page is for Agent Handler. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # SmartAdvocate **Authentication:** SmartAdvocate host, username, and password. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow. ## Sample use cases * Open a new case for a personal-injury client and set the case type. * List all appointments scheduled for case number 2024-0512. * Add the plaintiff's injuries and treatment details to the case. * Show me the outstanding tasks assigned to the litigation team. ## Available Tools #### list\_case\_appointments List every calendar appointment on one case by internal case ID. Not paginated — returns the case's full appointment... #### list\_appointments\_by\_case\_number List every calendar appointment on one case by its human-readable case number. Use list\_case\_appointments when you al... #### search\_appointments Search appointments across cases for firm-wide calendars and deadline reports. The modified-date window is required;... #### create\_appointment Schedule an appointment on a case — a hearing, deposition, meeting, or reminder. Call list\_appointment\_types, list\_ap... #### list\_appointment\_types List the firm's appointment types, e.g. Deposition or Trial. Call this before create\_appointment — type IDs are per-f... #### list\_appointment\_activity\_types List the firm's appointment activity types — the secondary classification on an appointment. Call this before create\_... #### list\_appointment\_statuses List the firm's appointment statuses, e.g. Scheduled or Cancelled. Call this before create\_appointment. #### list\_case\_calls List the calls logged on one case — remote party, number, direction, date, and summary. Page with page\_info.next\_page. #### create\_call Log a phone call on a case. direction is true for outbound and false for inbound. Use list\_case\_contacts or lookup\_co... #### update\_call Replace a logged call in full. Every field you want kept must be supplied — omitted fields are cleared. Use patch\_cal... #### patch\_call Change selected fields on a logged call, leaving the others untouched. Pass fields as a mapping of API field name to... #### delete\_call Delete a logged call from a case permanently. This cannot be undone. #### get\_case Get one case by its internal case ID, including parties, staff, tags, and incident summary. Use get\_case\_info instead... #### get\_case\_info Get a case by its human-readable case number, e.g. 9000002. Use get\_case instead when you already have the internal c... #### search\_cases Search cases modified within a date range, optionally narrowed by case number, case type, case group, or tag. The dat... #### list\_active\_cases List open cases assigned to one staff member, for workload or dashboard views. Use list\_case\_staff on a known case to... #### create\_case Open a new case from intake details. Call list\_case\_groups and list\_case\_types first — group and type IDs are per-fir... #### update\_case\_number Change a case's human-readable case number. The firm must have case-number editing enabled in SmartAdvocate and the n... #### list\_case\_contacts List every contact linked to a case with the role each one holds — plaintiff, defendant, witness, adjuster, and so on... #### add\_case\_contact Link an existing contact to a case in a role. Find the contact ID with lookup\_contacts or search\_contacts, or create... #### update\_case\_contact Replace a case-contact link's role and comments. This is a full replacement — any field left unset is cleared. Use pa... #### patch\_case\_contact Change selected fields on a case-contact link, leaving the others untouched. Pass fields as a mapping of field name t... #### delete\_case\_contact Unlink a contact from a case. This removes the case-contact relationship only; the contact record itself is left in p... #### list\_related\_cases List cases linked to this one as related matters — consolidated cases, companion cases, or other cases involving the... #### list\_case\_groups List the firm's case groups — the top-level case classification, e.g. Personal Injury. Call this before create\_case o... #### list\_case\_types List the case types inside one case group — the second-level classification. Get the group ID from list\_case\_groups.... #### list\_case\_subtypes List the subtypes inside one case type — the third-level classification. Get the case type ID from list\_case\_types. R... #### get\_contact Get a contact's core details by contact ID — name, primary address, phone, and email. Use get\_contact\_full for the co... #### get\_contact\_full Get a contact's complete record, including all addresses, emails, phones, and classification fields. Heavier than get... #### search\_contacts Search contacts by modified-date window, optionally restricted to those linked to given case numbers. The date window\... #### lookup\_contacts Find contacts by name or phone number — the way to resolve a person to a contact ID before add\_case\_contact, add\_plai... #### create\_contact Create a contact. Call list\_contact\_types first — category and type IDs are per-firm configuration. Give first\_name a... #### patch\_contact Change selected fields on a contact, leaving the others untouched. Pass fields as a mapping of API field name to new\... #### list\_related\_contacts List contacts related to a given contact, with the relationship each one holds — family members, employers, and simil... #### list\_contact\_addresses List a contact's postal addresses. Returns the address IDs patch\_contact\_address and delete\_contact\_address take. #### add\_contact\_addresses Add one or more postal addresses to a contact. Pass a list even for a single address. Use list\_incident\_states for va... #### patch\_contact\_address Change selected fields on one of a contact's addresses. Get the address ID from list\_contact\_addresses. Pass fields a... #### delete\_contact\_address Delete one address from a contact permanently. This cannot be undone. #### list\_contact\_emails List a contact's email addresses. The address itself is in the `name` field. Returns the email IDs patch\_contact\_emai... #### add\_contact\_emails Add one or more email addresses to a contact. Pass a list even for a single address. Set prevent\_auto\_contact to stop... #### patch\_contact\_email Change selected fields on one of a contact's email addresses. The address itself is the `name` field. Get the email I... #### delete\_contact\_email Delete one email address from a contact permanently. This cannot be undone. #### list\_contact\_phones List a contact's phone numbers with their labels and texting flags. Returns the phone IDs patch\_contact\_phone and del... #### add\_contact\_phones Add one or more phone numbers to a contact. Pass a list even for a single number. Use list\_phone\_types for the labels... #### patch\_contact\_phone Change selected fields on one of a contact's phone numbers. Get the phone ID from list\_contact\_phones. Pass fields as... #### delete\_contact\_phone Delete one phone number from a contact permanently. This cannot be undone. #### list\_contact\_types List the firm's contact types for a contact category. Call this before create\_contact — the category and type IDs are... #### list\_address\_types List the firm's address types for a contact category, for labelling addresses on a contact. #### list\_phone\_types List the firm's phone types, e.g. Mobile Phone or Work Phone. Use one of these as the name when calling add\_contact\_p... #### list\_contact\_subcategories List the firm's contact subcategories. Feeds contact\_sub\_category\_id on create\_contact. #### list\_case\_documents List document metadata for one case, filtered server-side by category, subcategory, or originating/destination contac... #### list\_documents\_by\_case\_number List document metadata for one case by its human-readable case number, with the same category and contact filters. Us... #### get\_document Get one document's metadata by document ID — name, category, dates, and review state. Returns no file content; use do... #### search\_documents Search document metadata across cases by modified-date window, narrowed by case number, category, subcategory, or con... #### create\_document Create a document metadata record on a case. This moves no bytes — call upload\_document\_content with the returned doc... #### update\_document Replace a document's metadata in full. Every field you want kept must be supplied — omitted fields are cleared. Use p... #### patch\_document Change selected metadata fields on a document, leaving the others untouched. Pass fields as a mapping of API field na... #### download\_document Download a document's file content by document ID. Returns UTF-8 text as text and anything else as base64 — check the... #### upload\_document\_content Attach file content to an existing document record. Pass the bytes as base64 in content\_base64, or a file\_reference f... #### list\_document\_categories List the firm's document categories with their subcategories, one row per category/subcategory pair. Call this before... #### list\_document\_folders List the document folders configured on one case. Use a folder name as document\_folder on create\_document to file a d... #### list\_document\_tags List the firm's document tags. Call this before create\_document to pass valid tag\_ids. #### get\_case\_incident Get a case's incident record — the facts of what happened plus structured details like date, state, and county. Retur... #### get\_incident\_by\_case\_number Get a case's incident record by its human-readable case number. Use get\_case\_incident when you already have the inter... #### search\_incidents Search incident records across cases by modified-date window, optionally restricted to specific case numbers. The dat... #### update\_incident Replace a case's incident facts and structured details. Get the incident ID from get\_case\_incident. Supplying inciden... #### patch\_incident Change selected fields on a case's incident record, leaving the others untouched. Pass fields as a mapping of API fie... #### list\_incident\_states List the states available on incident records. Call this before update\_incident to get a valid state ID, or to resolv... #### list\_incident\_counties List the counties available on incident records. This is a large reference list covering every state; call it before... #### list\_liability\_codes List the firm's liability codes for incident records. Call this before update\_incident — these IDs are per-firm confi... #### list\_case\_injuries List the injury records on a case, one per injured plaintiff. Returns the injury IDs the injury-detail tools take. Us... #### get\_injury Get one injury record on a case, including its summaries and confinement details. Use list\_case\_injuries to find inju... #### search\_injuries Search injury records across cases by modified-date window, optionally restricted to specific case numbers. The date... #### create\_injury Create an injury record for one plaintiff on a case. plaintiff\_id is the plaintiff RECORD id from list\_plaintiffs, no... #### update\_injury Replace an injury record's summaries, confinement details, and comments. Fields left unset are cleared, so supply eve... #### delete\_injury Delete an injury record from a case permanently, along with its detail rows. This cannot be undone. #### list\_injury\_details List the detail rows under one injury — each a body part with its treatments and sequelae. Returns the detail row IDs... #### get\_injury\_detail Get one injury detail row by its ID. Use list\_injury\_details to find row IDs. #### create\_injury\_detail Add a body-part detail row to an injury. Call list\_body\_parts first, then list\_treatments and list\_sequelae with that... #### update\_injury\_detail Replace an injury detail row. Fields left unset are cleared, so supply everything you want kept. Use patch\_injury\_det... #### patch\_injury\_detail Change selected fields on an injury detail row, leaving the others untouched. Pass fields as a mapping of API field n... #### delete\_injury\_detail Delete one injury detail row permanently. This cannot be undone. #### add\_injury\_details\_by\_icd Add injury detail rows from ICD diagnosis codes, letting SmartAdvocate map each code to the right body part and injur... #### add\_injury\_details\_by\_cpt Add procedure detail rows to an injury from CPT procedure codes, letting SmartAdvocate map each code to the right tre... #### list\_body\_parts List the body parts available on injury detail rows. Call this first when building a detail row, then feed the ID to... #### list\_sequelae List the sequelae — follow-on conditions — recorded for one body part. Feeds sequelae\_ids on create\_injury\_detail. Us... #### list\_treatments List the treatments available for one body part. Feeds treatment\_ids on create\_injury\_detail. Use list\_body\_parts to... #### list\_injury\_names List the firm's catalogue of injury names. This is a large reference list; use it to resolve an injury description to... #### list\_case\_insurance List the insurance policies on a case for one side. party is required: 'P' for plaintiff-side coverage, 'D' for defen... #### list\_insurance\_by\_case\_number List insurance policies for one side of a case by its human-readable case number. Use list\_case\_insurance when you al... #### get\_insurance Get one insurance policy on a case by its insurance record ID, including carrier, adjuster, limits, and claim number. #### create\_insurance Record an insurance policy on a case. Set party to 'P' or 'D' and pass the matching plaintiff\_id or defendant\_id from... #### update\_insurance Replace an insurance policy in full. Fields left unset are cleared, so supply everything you want kept, including par... #### patch\_insurance Change selected fields on an insurance policy, leaving the others untouched. Pass fields as a mapping of API field na... #### delete\_insurance Delete an insurance policy from a case permanently. This cannot be undone. #### list\_insurance\_types List the firm's insurance types, e.g. auto liability or health. Call this before create\_insurance — these IDs are per... #### list\_case\_notes List the notes on one case by internal case ID, newest first. Use list\_notes\_by\_case\_number when you only have the ca... #### list\_notes\_by\_case\_number List the notes on one case by its human-readable case number. Use list\_case\_notes when you already have the internal... #### get\_note Get one case note by its note ID, including full body text and sharing settings. #### search\_notes Search notes across cases by modified-date window, optionally restricted to specific case numbers. The date window is... #### create\_note Add a note to a case. Call list\_note\_types first — note type IDs are per-firm configuration. note\_text accepts HTML.... #### update\_note Replace a note in full — type, body, date, subject, contact, priority and sharing. Every field left unset is cleared,... #### patch\_note Change selected fields on a note, leaving the others untouched. Pass fields as a mapping of API field name to new val... #### list\_note\_types List the firm's note types. Call this before create\_note or update\_note — note type IDs are per-firm configuration an... #### list\_plaintiffs List the plaintiffs on a case with their roles and contact IDs. Set add\_contact\_info to include full contact details,... #### list\_defendants List the defendants on a case with their roles and contact IDs. #### add\_plaintiff Add a plaintiff to a case. Call list\_plaintiff\_roles first with the case's type ID — role IDs are per-firm configurat... #### patch\_plaintiff Change selected fields on a plaintiff record, leaving the others untouched. Pass fields as a mapping of API field nam... #### list\_plaintiff\_roles List the plaintiff roles available for a case type, e.g. Passenger or Driver. Call this before add\_plaintiff — role I... #### lookup\_cases Look up cases by a single criterion, e.g. every case with a given status. Pass the value as criteria and what it refe... #### list\_case\_staff List the staff assigned to one case with their roles. This is the discovery tool for staff IDs: it returns the contac... #### list\_staff\_by\_case\_number List staff assignments by case number. Accepts % as a wildcard, so '1%' returns assignments for every case whose numb... #### search\_case\_staff Search staff assignments across cases by modified-date window, optionally restricted to specific case numbers. The da... #### list\_case\_statuses List a case's status history by internal case ID — each record with its type, value, and effective dates. A record wi... #### list\_statuses\_by\_case\_number List a case's status history by its human-readable case number. Use list\_case\_statuses when you already have the inte... #### get\_case\_status Get one case status record by its status record ID, with dates and comments. #### search\_case\_statuses Search case status records across cases by modified-date window, optionally restricted to specific case numbers. The... #### create\_case\_status Add a status record to a case. Call list\_status\_types first — both the status type ID and the status value ID within... #### update\_status\_comment Change the comment on an existing case status record. Only the comment can be edited; use create\_case\_status to recor... #### terminate\_case\_status Close out the active status of a given type on a case by stamping its end date. Nothing is deleted — the record stays... #### list\_status\_types List the firm's case status types and the status values inside each one. Call this before create\_case\_status or termi... #### list\_tags List every tag defined in the firm, with its active state and any case-group or case-type restrictions. Use list\_avai... #### get\_tag Get one tag definition by ID, including its group and case-type restrictions. #### create\_tag Define a new tag that can be applied to cases. Set limit\_groups true and pass groups to restrict it to certain case g... #### update\_tag Update a tag definition's name, active state, or group restrictions. This replaces the tag's properties, so supply ev... #### delete\_tag Delete a tag definition permanently. This also removes the tag from every case it was applied to and cannot be undone... #### list\_available\_case\_tags List the tags that can still be applied to one case — those allowed for its case group and type and not already assig... #### add\_case\_tags Apply one or more existing tags to a case. Call list\_available\_case\_tags first — a tag not permitted for the case's g... #### remove\_case\_tags Take one or more tags off a case. The tag definitions themselves are left intact — use delete\_tag to remove a definit... #### list\_case\_tasks List the tasks on one case by internal case ID. Use list\_tasks\_by\_case\_number when you only have the case number, or... #### list\_tasks\_by\_case\_number List the tasks on one case by its human-readable case number. Use list\_case\_tasks when you already have the internal... #### get\_task Get one task by its task ID, including assignee, dates, and attached documents. #### search\_tasks Search tasks across cases, filtering by modified window, due-date range, type, status, assignee, or template. All fil... #### create\_task Create a task on a case. Call list\_task\_types, list\_task\_statuses, and list\_task\_priorities first — these IDs are per... #### update\_task Replace a task in full. Every field you want kept must be supplied — omitted fields are cleared. Use patch\_task to ch... #### patch\_task Change selected fields on a task, leaving the others untouched. Pass fields as a mapping of API field name to new val... #### delete\_task Delete a task permanently by its task ID. This cannot be undone. #### list\_task\_types List the firm's task types. Call this before create\_task, update\_task, or search\_tasks — task type IDs are per-firm c... #### list\_task\_statuses List the firm's task statuses, e.g. Not Started or Completed. Call this before create\_task, update\_task, or search\_ta... #### list\_task\_priorities List the firm's task priority levels, e.g. Normal or High. Call this before create\_task or update\_task. #### list\_case\_udfs List a case's user-defined fields and their current values — SmartAdvocate's custom fields. This is the discovery too... #### list\_udfs\_by\_case\_number List a case's user-defined fields by its human-readable case number. Use list\_case\_udfs when you already have the int... #### get\_udf Get one user-defined field's value on a case by its UDF definition ID. Use list\_case\_udfs to find UDF IDs. #### search\_udfs Search user-defined field values across cases by modified-date window, optionally restricted to specific case numbers... #### update\_udf Set one user-defined field's value on a case. Call list\_case\_udfs first for the udfid, and pass its relatedPK as sub\_... #### bulk\_update\_udfs Set several user-defined field values on one case in a single transaction — if any entry is invalid nothing is writte... #### list\_udf\_grid\_rows List the rows of a UDF grid on a case. Get the screen name from the screen\_name of a grid-type field returned by list... #### get\_udf\_grid\_row Get one row of a UDF grid by row ID, returning each cell's column definition ID and value. Use list\_udf\_grid\_rows to... #### create\_udf\_grid\_row Add a row to a UDF grid on a case. Read the column definition IDs from an existing row with list\_udf\_grid\_rows first... #### update\_udf\_grid\_row Replace a UDF grid row's cells. This is a full replacement — include every column you want kept, with each cell's udf... #### delete\_udf\_grid\_row Delete a row from a UDF grid on a case. This cannot be undone.