The Prevail API lets approved applications read and write a law firm's Prevail case management records through this base URL: `https://portal.prevail.net/api/v1/prevail`. Use this overview to authenticate, send requests, and understand common request and response patterns. The generated endpoint reference below this overview is the source of truth for canonical paths, parameters, request bodies, and response fields. ## Contents - **Overview:** [At a Glance](#at-a-glance), [Base URL](#base-url), [Getting Access](#getting-access), [Authentication](#authentication), [Security Best Practices](#security-best-practices), [Sensitive Data and Logging](#sensitive-data-and-logging), [Quick Start](#quick-start), [Common Read Examples](#common-read-examples), [Testing Your Credentials](#testing-your-credentials) - **Developer Guide:** [Glossary](#glossary), [Core Concepts](#core-concepts), [Firm Connection Availability](#firm-connection-availability), [Common Request Rules](#common-request-rules), [Deletes and Tombstones](#deletes-and-tombstones), [Matter ID Naming](#matter-id-naming), [Field Formats](#field-formats), [Lookup Values](#lookup-values), [Filtering](#filtering), [Pagination](#pagination), [Sorting](#sorting), [Incremental Sync](#incremental-sync), [Webhooks and Polling](#webhooks-and-polling) - **Resource Reference Summary:** [Resources](#resources), [Resource Endpoint Summaries](#resource-endpoint-summaries), [Create and Update Requests](#create-and-update-requests) - **Operations and Support:** [Idempotency and Safe Retries](#idempotency-and-safe-retries), [Rate Limits and Request Volume](#rate-limits-and-request-volume), [Response Format](#response-format), [Error Responses](#error-responses), [Timeouts](#timeouts), [Troubleshooting](#troubleshooting), [Versioning](#versioning), [Support](#support) ## At a Glance | Item | Details | |---|---| | **Current Version** | `v1` | | **Base URL** | `https://portal.prevail.net/api/v1/prevail` | | **Response Format** | JSON, except document file downloads return binary content | | **Authentication** | Client ID and Client Secret request headers | | **Main Resources** | Matters, Prospects, Contacts, Documents, Ledger, Payments, Trust Payments, Trust Deposits, Medical, Employment, Disability, Process, SMS Messages, Damages, Liens, Negotiations, Evidence, Tasks, Appointments, and Lookups | | **API Reference** | See the endpoint reference below this overview | ## Base URL Base URL: ```http https://portal.prevail.net/api/v1/prevail ``` All endpoint paths in this overview are relative to the versioned Prevail API path. Use the Base URL shown above, or the environment-specific Base URL provided during onboarding. The URL shown here is generated from this environment's configured application URL. In local development, a `prevail-master-portal.test` host must resolve in your development environment before requests can reach the API. Path convention: Use `/...` in curl examples. Use `/...` paths in tables and prose when the path is relative to ``. Use `/api/v1/prevail/...` only in raw HTTP examples or when explaining versioning. Do not append `/api/v1/prevail` again after ``. ## Getting Access Before making requests, get an API credential from the law firm whose Prevail records your integration will access: - `Client ID` - `Client Secret` An API credential consists of a Client ID and Client Secret. API credentials are firm-specific API key records. The law firm can generate API credentials from Prevail by navigating to Administration > Firm Settings > API. Outside developers cannot self-register API credentials from this documentation. An authorized user at the law firm must generate the Client ID and Client Secret, then provide them to the approved integration owner through a secure channel; contact the law firm or Prevail support for onboarding instructions. **Credential scope:** API credentials are firm-specific. A valid Client ID and Client Secret only authorize access for the law firm that issued them. ### Credential lifecycle - API credentials are stored as API key records linked to a law firm. Treat the Client ID and Client Secret as secrets and store them server-side only. - API credentials can be created and deleted; inactive or expired API keys are rejected when those controls are set. Newly generated API credentials do not set an expiration date by default. - If API credentials are exposed, ask the law firm or Prevail support to revoke, disable, or replace the API key record, then update the integration with the replacement API credentials. - Prevail API requests are audited with the API key ID, request URL, IP address, redacted credential headers, and timestamp. ## Authentication Every request must include both API credential headers issued by the law firm. | Header | Required | Description | |---|---|---| | `X-Client-ID` | Yes | Client ID from the API credential. | | `X-Client-Secret` | Yes | Client Secret from the API credential. | | `Accept` | Recommended for JSON metadata requests | Use `application/json` for API metadata requests and JSON error responses. Document file download endpoints return binary content on success. | | `Content-Type` | Required for `POST`, `PUT`, and `PATCH` requests | Use `application/json` for JSON bodies. Use `multipart/form-data` for file upload endpoints. | | `Idempotency-Key` | Optional for `POST` and `PATCH` requests | Caller-generated safe retry key. Use letters, numbers, `.`, `_`, `:`, or `-`; maximum 80 characters. | Example: ```http X-Client-ID: X-Client-Secret: Accept: application/json ``` ## Security Best Practices **Keep secrets server-side:** Treat the Client Secret like a password. Do not send it to browsers, mobile clients, public logs, or support channels. The Prevail API is intended for server-to-server integrations. Do not call it directly from browser JavaScript or mobile client code because those clients cannot safely store the Client Secret. - Store the Client Secret server-side only. - Use HTTPS for every non-local API request. Production API requests must use HTTPS, especially when transmitting sensitive contact data such as Social Security numbers. - Never expose API credentials in frontend JavaScript, mobile apps, public repositories, support tickets, or logs. - Never send API credentials in query string parameters. - Do not log full request headers because they may contain API credentials. - Replace API credentials if they are exposed, delete the old API key record, and create a new one in the firm's Prevail API settings.' - Log endpoint paths, timestamps, request IDs when returned, and status codes for troubleshooting, but do not log secrets. - Only give API credentials to approved applications that need access to the law firm's Prevail records. ## Sensitive Data and Logging Prevail records may contain sensitive client, matter, medical, financial, or personally identifiable information. - Do not log full request or response bodies in deployed integrations unless your system has been approved to store that data securely. - Do not log Social Security numbers, full phone numbers, dates of birth, client notes, medical details, or document contents unless required by your integration and approved by the law firm. - Mask sensitive values in logs when possible, such as showing only the last 4 digits of a Social Security number. - Store any cached API records securely and only for as long as your integration needs them. - Only request the fields and records your integration needs. - Do not include API credentials, Social Security numbers, or full client data in support tickets unless Prevail support specifically requests them through an approved secure channel. ## Quick Start ### Response Shape Reminder Prevail API responses are endpoint-specific. The API does not use one global response wrapper, and successful API responses do not include internal relay fields such as `request_id` and `data`. Error responses from the connected Prevail desktop may include a `request_id` for troubleshooting. Matter and prospect list endpoints return `matters` or `prospects`; detail endpoints return `matter` or `prospect`; matter/prospect create and update endpoints return top-level `matterid`. Other resources use endpoint-specific keys such as `contacts`, `documents`, `payments`, `task`, or `appointment`. Build clients against each endpoint's documented response example. ### 1. Send the Required Headers Every request needs the API credential headers issued by the law firm and an `Accept: application/json` header. ```http X-Client-ID: X-Client-Secret: Accept: application/json ``` For JSON write requests, also send: ```http Content-Type: application/json ``` For document uploads, use `multipart/form-data` instead of JSON. ### 2. Make a Read-Only Test Request Start with a small `GET` request so you can verify API credentials and the connected Prevail system before sending writes. ```bash curl --request GET "/matters?openclosed=open" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ### 3. Pick the Workflow | Workflow | Start With | Use When | |---|---|---| | Find a matter | `GET /matters?openclosed=open` | You need matter IDs before reading related records. | | Find a contact | `GET /contacts?search=smith` | You need a contact ID before linking contacts or using provider fields. | | Read documents | `GET /documents?matter_id=` | You need document metadata before downloading or replacing files. | | Use law firm values | `GET /lookups/...` | You need valid types, categories, subjects, users, offices, locations, or statuses. | | Create or update data | Resource-specific `POST` or `PATCH` | You already have required IDs and lookup values. | ### 4. Copy-Ready Examples Use these examples for the first small read requests after credential testing. See [Common Read Examples](#common-read-examples) for more resource-specific read examples. #### Contact Search ```bash curl --request GET "/contacts?search=smith" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Matter Documents ```bash curl --request GET "/documents?matter_id=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Appointment Location Lookup ```bash curl --request GET "/lookups/appointment-locations" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ## Common Read Examples Skip this section if you already know which resource you need; these examples show common read patterns only. These examples use the same required headers as Quick Start. In this documentation, `` means `https://portal.prevail.net/api/v1/prevail`. #### Matter Ledger ```bash curl --request GET "/matters//ledger?type=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Payment Search ```bash curl --request GET "/payments?matter_id=&category=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Medical Records ```bash curl --request GET "/matters//medical?record_type=Medical%20Record" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Employment Records ```bash curl --request GET "/employment?matter_id=&employer_name=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Disability Records ```bash curl --request GET "/disability?matter_id=&ailment=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Damage Records ```bash curl --request GET "/damages?matter_id=&type=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Lien Metadata ```bash curl --request GET "/liens?matter_id=&subject=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Negotiation Metadata ```bash curl --request GET "/negotiations?matter_id=&type=Demand" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Claims Process Records ```bash curl --request GET "/processes?matter_id=&status=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Open Tasks ```bash curl --request GET "/matters//tasks?status=Open" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` #### Appointments ```bash curl --request GET "/appointments?assigned_to=KIM&date_start=2026-04-22&date_end=2026-04-22" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ## Testing Your Credentials Use any endpoint from Quick Start to confirm that your API credentials are valid. V1 does not expose a separate customer health-check endpoint; use a small read-only `GET` request to verify both API credentials and connected Prevail system availability. If API credentials are valid and the connected Prevail system is available, the API returns a JSON response. A `200 OK` response means the API credentials worked, even if no records are returned. If API credentials are missing or wrong, the API returns a `401 Unauthorized` response. A `503` or `504` response can still occur with valid API credentials when the connected Prevail system is unavailable or does not respond in time. ## Glossary | Term | Meaning | |---|---| | Firm | The law firm whose Prevail records an API credential can access. | | Matter | A case record in Prevail. | | Prospect | An intake or pre-matter record in Prevail. | | Lookup value | A firm-configured value used by fields such as `type`, `category`, `subject`, `status`, `location`, or `assigned_to`. | | Metadata-only resource | A resource that stores record details but does not upload, download, replace, or stream file content. | | Connected Prevail system | The firm's connected Prevail application or system that receives API requests and returns results. | ## Core Concepts ### Firm-scoped API credentials API credentials are firm-specific. They authorize access only for the firm that issued them; see [Getting Access](#getting-access) and [Authentication](#authentication) for header requirements. ### `matter_id` versus `matterid` Use `matter_id` for firm-level query filters when an endpoint documents a matter filter. Matter-scoped path routes use `{matterid}`, and response fields may also use `matterid`; see [Matter ID Naming](#matter-id-naming) for the compatibility rules. ### Lookup-backed values Fields such as `type`, `category`, `subject`, `status`, `location`, and `assigned_to` often must match firm-specific Prevail lookup values exactly. Use lookup endpoints before create or update requests that depend on configured values. ### Opaque record IDs Treat record IDs as opaque strings, even when they look numeric. Use IDs returned by the API and check the endpoint reference for the exact ID field name. ### Firm connection availability Many requests depend on the firm's connected Prevail system; see [Firm Connection Availability](#firm-connection-availability) for `501`, `503`, and `504` behavior. ### Response shape differences The API does not use one global response wrapper. Build clients against each endpoint's documented response example; the endpoint reference below remains the source of truth for canonical paths, parameters, bodies, and response fields. ## Firm Connection Availability The API forwards most Prevail API requests to the connected Prevail system before returning records. Valid API credential headers authenticate the integration, but they do not guarantee the connected Prevail system is online or supports every V1 capability. With valid API credentials, clients may still receive `501 Capability Unavailable`, `503 Prevail Unavailable`, or `504 Timeout`. Runtime error messages may use the implementation wording `Prevail desktop`; exact messages include `Prevail desktop has not implemented: `, `Prevail desktop is not connected`, and `Timeout: no response from Prevail desktop`. See [Error Responses](#error-responses) and [Timeouts](#timeouts) for handling guidance. ## Common Request Rules - Responses use JSON. Requests use JSON except file upload endpoints, which use `multipart/form-data`. - Use the HTTP method shown for each endpoint. - Send JSON request bodies with the `Content-Type: application/json` header. - Do not send blank strings or `null` values unless the endpoint specifically allows clearing that field. - Treat record IDs as strings, even when they look numeric. - The API reference is the source of truth for canonical methods, paths, parameters, request bodies, and response fields. ## Deletes and Tombstones V1 does not expose public delete endpoints unless an endpoint explicitly documents one. Actions such as task complete/reopen and appointment cancel/reschedule are workflow or status transitions, not record deletion. Deleted records may be omitted from list and detail responses. V1 does not provide deletion tombstones unless an endpoint explicitly states otherwise. Appointment endpoints preserve their documented behavior: private and deleted appointments are omitted and return not found for detail or update requests, while cancelled non-deleted appointments remain visible with status `Cancelled`. ## Matter ID Naming Use `matter_id` for firm-level query filters when an endpoint documents a matter filter. Some older endpoints also accept the legacy `matterid` query field for compatibility; when both aliases are accepted, they must identify the same Prevail matter. Matter-scoped routes use `{matterid}` in the path because `matterid` is Prevail's native field name. On those routes, the path value is authoritative; do not also send `matter_id` or `matterid` query filters unless the endpoint documents them. When a write body accepts `matter_id`, it must match the path matter ID. Response payloads may also use `matterid`. Treat `matter_id` and `matterid` as the same Prevail matter identifier unless an endpoint documents different behavior. ## Field Formats Use the formats shown below unless an endpoint documents a different format. The endpoint reference remains authoritative for which fields each endpoint accepts and which validations are enforced before requests are forwarded to the connected Prevail system. | Group | Use For | |---|---| | General formats | Shared date, time, ID, boolean, empty-value, and pass-through value handling. | | Financial formats | Ledger, payment, trust payment, trust deposit, and idempotency values. | | Lookup-backed resource values | Fields that should match firm-configured lookup values before filtering, creating, or updating records. | | Read-only resource filters | Resource-specific filters for endpoints that do not support create or update in V1. | | Metadata-only resource values | Values for resources that store record metadata but do not manage file content. | **Time zone note:** Date-only fields use `YYYY-MM-DD`; `updated_since` is validated as a date filter, not a timestamp. Appointment `date`, `end_date`, `start_time`, and `end_time` values are firm-local. Response timestamp fields such as `created` and `modified` are returned from the connected Prevail system; this overview does not define one global UTC, firm-local, or server-local timezone for those values. The endpoint reference is authoritative for field-specific examples and timezone notes, and clients should preserve returned timestamp values. **General formats** | Field Type | Format | Example | Notes | |---|---|---|---| | Date filters | `YYYY-MM-DD` | `2026-04-22` | Use for date-only filters and date-only request values. | | Full date/time values | ISO 8601 when documented by the endpoint | `2026-04-22T14:30:00` | Use only when an endpoint explicitly accepts a full date/time value. | | Time-only values | `HH:MM` or `HH:MM:SS` when documented by the endpoint | `14:30` | Use 24-hour time when an endpoint accepts time-only values. | | Appointment date and time fields | `date` and `end_date` use `YYYY-MM-DD`; `start_time` and `end_time` use `HH:MM` or `HH:MM:SS` | `2026-04-22`, `2026-04-23`, `14:30`, `15:00` | Appointment V1 request and response values are firm-local `date`, `end_date`, `start_time`, and `end_time` fields. | | Phone number filters | 10 digits, no dashes or spaces | `9999999999` | Send only the phone number digits unless the endpoint documents another format. | | Contact Social Security number | 9 digits or `###-##-####`; `null` when clearing | `123-45-6789` | The full value is returned only by `GET /contacts/{contact_id}`; contact lists and write responses omit it. | | Matter and prospect boolean request fields | JSON boolean or numeric boolean | `true`, `false`, `1`, or `0` | Use for create/update boolean fields such as `active`, `solconfirm`, `archived`, `statuteoverride`, and `settlementcalculator`. | | Contact communication boolean request fields | JSON boolean or string boolean | `true`, `false`, `"true"`, or `"false"` | Use for communication fields such as `international`, `primary`, and `messages`. These are normalized before being sent to Prevail. | | Prevail boolean response values | String value returned by Prevail | `True` or `False` | Many Prevail fields are returned as strings. Preserve returned values unless your integration maps them intentionally. | | Matter ID filters and path values | Alphanumeric string, maximum 25 characters | `12W34qop12` | Use `matter_id` for firm-list filters. Path values and response fields may use Prevail's `matterid` name. Do not include spaces or punctuation. | | Record IDs | String value returned by the API | `12W34qop12` | Do not assume IDs are numeric. | | Empty values | Omit the field unless clearing is documented | N/A | Do not send blank strings or `null` unless the endpoint specifically allows clearing that field. | | Unknown or custom fields | Preserve exactly as returned | N/A | Firm-specific fields may vary. Preserve names and values exactly unless your integration has a firm-specific mapping. | **Financial formats** | Field Type | Format | Example | Notes | |---|---|---|---| | Ledger amount values | JSON number or numeric string when documented by the endpoint | `` | Do not include currency symbols or thousands separators. | | Payment amount values | Non-negative JSON number or numeric string when documented by the endpoint | `` | Do not include currency symbols, thousands separators, or negative values. | | Trust accounting amount values | Non-negative JSON number or numeric string when documented by the endpoint | `` | Do not include currency symbols, thousands separators, or negative values. | | Idempotency keys for trust accounting creates | Caller-generated string, maximum 80 characters | `matter-12W34qop12-trust-payment-20260422-1` | Use letters, numbers, `.`, `_`, `:`, or `-`; reuse the same key only when retrying the same create request. The API validates and forwards this key to the connected Prevail system, where duplicate detection is performed. | **Lookup-backed resource values** | Field Type | Format | Example | Notes | |---|---|---|---| | Lookup values | Exact Prevail value | `PI`, `Auto Accident`, `DEFAULT` | Preserve spelling, spacing, and capitalization exactly as returned or configured by the firm. | | Ledger type, category, and subject values | Exact Prevail lookup value | `` | Use the ledger lookup endpoints before filtering, creating, or updating ledger entries. Categories and subjects may depend on the selected ledger type. | | Payment category and subject values | Exact Prevail lookup value | `` | Use the payment lookup endpoints before filtering, creating, or updating payment records. | | Trust payment category and subject values | Exact Prevail lookup value | `` | Use the trust payment lookup endpoints before filtering, creating, or updating trust payment records. | | Trust deposit category and subject values | Exact Prevail lookup value | `` | Use the trust deposit lookup endpoints before filtering, creating, or updating trust deposit records. | | Medical record type, status, ailment, and ICD values | Exact Prevail lookup or accepted record type value | `Medical Record` | `record_type` accepts only `Medical Record`, `Medical`, `Medical Rqstd`, or `Medical Rcvd`. Use medical lookup endpoints for firm-specific status, ailment, and ICD values. | | History type, category, and subject values | Exact Prevail lookup value or firm-approved free text | `History` | Use history lookup endpoints before filtering, creating, or updating ordinary history records. History subjects may be free typed when the firm workflow allows it. | **Read-only resource filters** | Field Type | Format | Example | Notes | |---|---|---|---| | Employment record filters | Exact Prevail value or text filter documented by the endpoint | `` | Employment record endpoints are read-only. Preserve returned values exactly unless your integration has a firm-specific mapping. | | Disability record filters | Exact Prevail value or text filter documented by the endpoint | `` | Disability endpoints are read-only. Preserve returned values exactly unless your integration has a firm-specific mapping. | | Process record filters | Exact Prevail process value or text filter documented by the endpoint | `` | Process endpoints are read-only and may be referred to as claims process endpoints. Preserve returned values exactly unless your integration has a firm-specific mapping. | | SMS message filters | Exact status, direction, or text filter documented by the endpoint | `` | SMS message endpoints are read-only. They do not send messages or mark inbound messages as retrieved. | **Metadata-only resource values** | Field Type | Format | Example | Notes | |---|---|---|---| | Damage type and subject values | Exact Prevail lookup value | `` | Use the damage lookup endpoints before filtering, creating, or updating damage metadata records. Damage endpoints do not manage file content. | | Lien subject values | Exact Prevail lookup value | `` | Use the lien subject lookup endpoint before filtering, creating, or updating lien metadata records. | | Negotiation type and subject values | Exact accepted type and Prevail lookup value | `Demand` | `type` accepts only `Demand` or `Offer`. Use the negotiation subject lookup endpoint before filtering, creating, or updating negotiation metadata records. | | Evidence category and subject values | Exact Prevail lookup value | `` | Use the evidence lookup endpoints before filtering, creating, or updating evidence metadata records. Evidence endpoints do not manage file content. | Example date filter: ```http GET /api/v1/prevail/matters?intakedatestart=2026-04-22 ``` Example phone filter: ```http GET /api/v1/prevail/matters?phonenumber=9999999999 ``` ## Lookup Values Some request fields must match values configured in the firm's Prevail environment. Examples may include law types, case types, security groups, statuses, contact types, document categories, ledger categories, task subjects, appointment locations, evidence subjects, payment subjects, medical values, and other firm-specific lists. Use the documented lookup endpoints, or confirm valid values with the firm before sending create or update requests. This index shows the common lookup endpoints to call first. Prefix each path with ``. The endpoint reference remains authoritative for exact parameters and response fields. | Resource or workflow | Lookup endpoints | |---|---| | Matter, prospect, and case setup | `/lookups/law-types`, `/lookups/case-types/{law_type}`, `/lookups/case-statuses/{law_type}`, `/lookups/custom-fields/matter/{law_type}`, `/lookups/security-groups`, `/lookups/branch-offices` | | Contact setup and communication | `/lookups/contact-types`, `/lookups/custom-fields/contact/{contact_type}`, `/lookups/communication-categories`, `/lookups/salutations`, `/lookups/suffixes`, `/lookups/titles`, `/lookups/languages`, `/lookups/countries`, `/lookups/specialties`, `/lookups/branch-offices` | | Staff assignment and security | `/lookups/users`, `/lookups/user-security-groups`, `/lookups/security-groups` | | Documents | `/lookups/document-categories` | | Tasks | `/lookups/task-types`, `/lookups/task-subjects`, `/lookups/users` | | Appointments | `/lookups/appointment-types`, `/lookups/appointment-subjects`, `/lookups/appointment-locations`, `/lookups/users` | | Ledger entries | `/lookups/ledger-types`, `/lookups/ledger-categories?type=`, `/lookups/ledger-subjects?type=` | | Payments | `/lookups/payment-categories`, `/lookups/payment-subjects` | | Trust payments and trust deposits | `/lookups/trust-payment-categories`, `/lookups/trust-payment-subjects`, `/lookups/trust-deposit-categories`, `/lookups/trust-deposit-subjects` | | Medical and disability values | `/lookups/history-types`, `/lookups/history-categories`, `/lookups/ailments`, `/lookups/icd-codes` | | History records | `/lookups/history-types`, `/lookups/history-categories`, `/lookups/history-subjects` | | Metadata-only records | `/lookups/damage-types`, `/lookups/damage-subjects`, `/lookups/lien-subjects`, `/lookups/negotiation-subjects`, `/lookups/evidence-categories`, `/lookups/evidence-subjects` | Lookup endpoints use `GET` and return the lookup payload directly, such as an object containing `appointment_locations`. Most lookup endpoints do not require request fields. Endpoints with path values, such as `{law_type}`, require those path parameters. Some endpoints also document query filters; ledger category and subject lookups require `type=`. Use `/lookups/custom-fields` to list every Law Type and Contact Type with configured custom fields. Use `/lookups/custom-fields/matter/{law_type}` or `/lookups/custom-fields/contact/{contact_type}` for one layout. Send custom-field values through the existing matter, prospect, or contact create/update endpoint as a `custom_fields` object keyed by the returned `title`; never send an internal database field name. Select values must match an option exactly, blank values are accepted only when `allow_blank` is true, and currency values are unformatted JSON numbers. Use `/lookups/contact-types` to retrieve valid contact types and `/lookups/communication-categories` to retrieve valid communication categories before creating or updating contacts. Contact setup fields may also depend on lookup values such as titles, salutations, suffixes, languages, countries, specialties, and branch offices. The users lookup can include each user's security group memberships by sending `include=security_groups`. Use `/lookups/user-security-groups` when you need a flat list of user, group, and role rows. Use `/lookups/task-types` and `/lookups/task-subjects` to retrieve firm-specific task values before creating or updating tasks. Use `/lookups/appointment-types`, `/lookups/appointment-subjects`, and `/lookups/appointment-locations` before creating or updating appointments. Appointment type values come from appointment types, subject values come from appointment subjects, and location values come from appointment locations. Use `/lookups/users` to choose valid `assigned_to` login values. Use `/lookups/ledger-types` to retrieve valid ledger types. After choosing a type, use `/lookups/ledger-categories?type=` and `/lookups/ledger-subjects?type=` to retrieve category and subject values for that type. The `type` query value must be one of `Cost`, `Fee`, or `Time`. Send returned lookup values exactly as provided by Prevail. Use `/lookups/payment-categories` and `/lookups/payment-subjects` to retrieve firm-specific payment values before filtering, creating, or updating payment records. Regular payment endpoints do not use the trust payment lookup endpoints. Use `/lookups/trust-payment-categories` and `/lookups/trust-payment-subjects` to retrieve firm-specific trust payment values before filtering, creating, or updating trust payment records. Use `/lookups/trust-deposit-categories` and `/lookups/trust-deposit-subjects` to retrieve firm-specific trust deposit values before filtering, creating, or updating trust deposit records. Trust payment and trust deposit lookup values are separate from regular payment lookup values. Use `/lookups/history-types`, `/lookups/history-categories`, `/lookups/ailments`, and `/lookups/icd-codes` to choose firm-specific values before creating or updating medical records. The `record_type` field is limited to `Medical Record`, `Medical`, `Medical Rqstd`, or `Medical Rcvd`. See [Metadata-only Resources](#metadata-only-resources) for medical file limitations. Use `/lookups/history-types`, `/lookups/history-categories`, and `/lookups/history-subjects` before filtering, creating, or updating ordinary matter history records. Employment record integrations can read employment history by matter or across the firm with filters documented in the endpoint reference. Employment record endpoints are read-only and return `employment_records` for lists and `employment_record` for single-record details. Disability integrations can read Prevail disability/ailment records by matter or across the firm with filters documented in the endpoint reference. Disability endpoints are read-only and return `disability_records` for lists and `disability_record` for single-record details. Process integrations can read Prevail process records, also referred to as claims process records, by matter or across the firm with filters documented in the endpoint reference. Process endpoints are read-only and return `process_records` for lists and `process_record` for single-record details. SMS integrations can read Prevail SMS message records by matter or across the firm with filters documented in the endpoint reference. SMS message endpoints are read-only and return `sms_messages` for lists and `sms_message` for single-record details. They do not send messages, update message status, or mark inbound messages as retrieved. Use `/lookups/damage-types` and `/lookups/damage-subjects` to choose firm-specific values before creating or updating damage metadata records. Use `/lookups/lien-subjects` to choose firm-specific subjects before creating or updating lien metadata records. Use `/lookups/negotiation-subjects` to choose firm-specific subjects before creating or updating negotiation metadata records. Use `/lookups/evidence-categories` and `/lookups/evidence-subjects` to choose firm-specific values before creating or updating evidence metadata records. See [Metadata-only Resources](#metadata-only-resources) for file limitations on metadata resources. ## Filtering Some list endpoints support query string filters. The API reference shows the exact supported filters for each endpoint. The table below is a quick index of common list filters. It omits pagination fields (`page`, `limit`) and sorting fields; see [Pagination](#pagination), [Sorting](#sorting), and the endpoint reference for the complete parameter list. | Resource | Common filters | |---|---| | Contacts | `search`, `type`, `first_name`, `last_name`, `company_name`, `email`, `phone`, `city`, `state`, `zip`, `updated_since`; matter contact lists also support `role`. | | Documents | `matter_id`, `category`, `filename`, `search`. | | Ledger | `matter_id`, `type`, `category`, `subject`, `search`, `entry_date_start`, `entry_date_end`, `updated_since`, `amount_min`, `amount_max`. | | Payments | `matter_id`, `category`, `subject`, `status`, `search`, `payment_date_start`, `payment_date_end`, `updated_since`, `amount_min`, `amount_max`. | | Trust Payments | `matter_id`, `category`, `subject`, `status`, `search`, `payment_date_start`, `payment_date_end`, `updated_since`, `amount_min`, `amount_max`. | | Trust Deposits | `matter_id`, `category`, `subject`, `status`, `search`, `deposit_date_start`, `deposit_date_end`, `updated_since`, `amount_min`, `amount_max`. | | Medical | `matter_id`, `record_type`, `status`, `provider_contact_id`, `provider_name`, `ailment`, `icd_code`, `search`, `from_date_start`, `from_date_end`, `received_date_start`, `received_date_end`, `date_start`, `date_end`, `updated_since`. | | Employment | `matter_id`, `employer_contact_id`, `contact_id`, `employer_name`, `job_title`, `employment_status`, `status`, `is_current`, `search`, `start_date_start`, `start_date_end`, `end_date_start`, `end_date_end`, `updated_since`. | | Disability | `matter_id`, `claimant_contact_id`, `contact_id`, `ailment`, `duration`, `severity`, `workload`, `search`, `created_start`, `created_end`, `updated_since`. | | Process | `matter_id`, `type`, `process_type`, `subject`, `process_name`, `status`, `stage`, `search`, `opened_date_start`, `opened_date_end`, `closed_date_start`, `closed_date_end`, `due_date_start`, `due_date_end`, `completed_date_start`, `completed_date_end`, `created_start`, `created_end`, `updated_since`. | | SMS Messages | `matter_id`, `direction`, `from_phone`, `to_phone`, `phone`, `status`, `search`, `sent_date_start`, `sent_date_end`, `received_date_start`, `received_date_end`, `date_start`, `date_end`, `updated_since`. | | Damages | `matter_id`, `type`, `subject`, `status`, `search`, `damage_date_start`, `damage_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`. | | Liens | `matter_id`, `subject`, `policy_number`, `client_contact_id`, `lienholder_contact_id`, `provider_contact_id`, `lien_date_start`, `lien_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`, `insured_amount_min`, `insured_amount_max`, `notice`, `include_in_settlement_calculator`, `search`. | | Negotiations | `matter_id`, `type`, `subject`, `final`, `search`, `negotiation_date_start`, `negotiation_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`, `percent_min`, `percent_max`, `alternate_settlement_calculator`, `include_damages_in_settlement_calculator`. | | Evidence | `matter_id`, `category`, `subject`, `status`, `source`, `location`, `search`, `evidence_date_start`, `evidence_date_end`, `date_start`, `date_end`, `received_date_start`, `received_date_end`, `collected_date_start`, `collected_date_end`, `updated_since`. | | Tasks | `matter_id`, `assigned_to`, `status`, `type`, `subject`, `search`, `due_date_start`, `due_date_end`, `updated_since`. | | Appointments | `matter_id`, `assigned_to`, `status`, `type`, `location`, `subject`, `search`, `date_start`, `date_end`, `updated_since`. | Use `matter_id` for firm-level matter filters. Some older firm-level list endpoints also accept the legacy `matterid` alias for compatibility; new integrations should send `matter_id`. Example matter filter: ```bash curl --request GET "/matters?openclosed=open" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ```http GET /api/v1/prevail/matters?search=smith GET /api/v1/prevail/matters?include=contacts GET /api/v1/prevail/matters/?include=contacts GET /api/v1/prevail/matters/?include=documents GET /api/v1/prevail/prospects?search=smith ``` Example contact filters: ```http GET /api/v1/prevail/contacts?search=smith GET /api/v1/prevail/contacts?type=Medical%20Provider GET /api/v1/prevail/contacts?company_name=Orlando GET /api/v1/prevail/contacts?phone=407 GET /api/v1/prevail/matters//contacts?role=Medical%20Provider GET /api/v1/prevail/contacts/123/communications?category=Phone GET /api/v1/prevail/contacts/123/addresses?address_type=mailing ``` Example document filters: ```http GET /api/v1/prevail/documents?matter_id= GET /api/v1/prevail/documents?category=Medical%20Records GET /api/v1/prevail/documents?search=records ``` Example ledger filters: ```http GET /api/v1/prevail/ledger?matter_id= GET /api/v1/prevail/ledger?type= GET /api/v1/prevail/matters//ledger?category= GET /api/v1/prevail/matters//ledger?entry_date_start=&entry_date_end= ``` Example payment filters: ```http GET /api/v1/prevail/payments?matter_id= GET /api/v1/prevail/payments?category= GET /api/v1/prevail/matters//payments?subject= GET /api/v1/prevail/payments?payment_date_start=&payment_date_end= GET /api/v1/prevail/payments?amount_min=&amount_max= ``` Example trust payment filters: ```http GET /api/v1/prevail/trust-payments?matter_id= GET /api/v1/prevail/trust-payments?category= GET /api/v1/prevail/matters//trust-payments?subject= GET /api/v1/prevail/trust-payments?payment_date_start=&payment_date_end= GET /api/v1/prevail/trust-payments?amount_min=&amount_max= ``` Example trust deposit filters: ```http GET /api/v1/prevail/trust-deposits?matter_id= GET /api/v1/prevail/trust-deposits?category= GET /api/v1/prevail/matters//trust-deposits?subject= GET /api/v1/prevail/trust-deposits?deposit_date_start=&deposit_date_end= GET /api/v1/prevail/trust-deposits?amount_min=&amount_max= ``` Example medical record filters: ```http GET /api/v1/prevail/medical?matter_id= GET /api/v1/prevail/medical?record_type=Medical%20Record GET /api/v1/prevail/matters//medical?provider_name= GET /api/v1/prevail/matters//medical?received_date_start=&received_date_end= GET /api/v1/prevail/matters//medical?date_start=&date_end= ``` Example employment record filters: ```http GET /api/v1/prevail/employment?matter_id= GET /api/v1/prevail/employment?employer_name= GET /api/v1/prevail/matters//employment?employment_status= GET /api/v1/prevail/matters//employment?start_date_start=&start_date_end= ``` Example disability filters: ```http GET /api/v1/prevail/disability?matter_id= GET /api/v1/prevail/disability?matterid= GET /api/v1/prevail/disability?claimant_contact_id= GET /api/v1/prevail/disability?ailment= GET /api/v1/prevail/disability?severity= GET /api/v1/prevail/disability?workload= GET /api/v1/prevail/matters//disability?search= GET /api/v1/prevail/disability?created_start=&created_end= ``` Example process filters: ```http GET /api/v1/prevail/processes?matter_id= GET /api/v1/prevail/processes?matterid= GET /api/v1/prevail/processes?type= GET /api/v1/prevail/processes?process_type= GET /api/v1/prevail/processes?process_name= GET /api/v1/prevail/processes?status= GET /api/v1/prevail/matters//processes?search= GET /api/v1/prevail/processes?opened_date_start=&opened_date_end= ``` Example SMS message filters: ```http GET /api/v1/prevail/sms-messages?matter_id= GET /api/v1/prevail/sms-messages?matterid= GET /api/v1/prevail/sms-messages?direction=outbound GET /api/v1/prevail/sms-messages?phone=9999999999 GET /api/v1/prevail/matters//sms-messages?search= GET /api/v1/prevail/sms-messages?sent_date_start=&sent_date_end= ``` Example damage filters: ```http GET /api/v1/prevail/damages?matter_id= GET /api/v1/prevail/damages?matterid= GET /api/v1/prevail/damages?type= GET /api/v1/prevail/damages?subject= GET /api/v1/prevail/damages?amount_min=&amount_max= GET /api/v1/prevail/matters//damages?search= GET /api/v1/prevail/damages?damage_date_start=&damage_date_end= ``` Example lien filters: ```http GET /api/v1/prevail/liens?matter_id= GET /api/v1/prevail/liens?matterid= GET /api/v1/prevail/liens?subject= GET /api/v1/prevail/liens?policy_number= GET /api/v1/prevail/liens?lienholder_contact_id= GET /api/v1/prevail/liens?provider_contact_id= GET /api/v1/prevail/liens?amount_min=&amount_max= GET /api/v1/prevail/liens?insured_amount_min=&insured_amount_max= GET /api/v1/prevail/liens?lien_date_start=&lien_date_end= GET /api/v1/prevail/matters//liens?search= ``` Example evidence filters: ```http GET /api/v1/prevail/evidence?matter_id= GET /api/v1/prevail/evidence?category= GET /api/v1/prevail/evidence?subject= GET /api/v1/prevail/matters//evidence?date_start=&date_end= ``` Example task filters: ```http GET /api/v1/prevail/tasks?assigned_to=KIM GET /api/v1/prevail/tasks?matter_id= GET /api/v1/prevail/matters//tasks?status=Open GET /api/v1/prevail/tasks?due_date_start=2026-04-22&due_date_end=2026-04-30 ``` Example appointment filters: ```http GET /api/v1/prevail/appointments?assigned_to=KIM GET /api/v1/prevail/appointments?matter_id= GET /api/v1/prevail/appointments?type=Client%20Meeting GET /api/v1/prevail/appointments?location=Main%20Office GET /api/v1/prevail/appointments?date_start=2026-04-22&date_end=2026-04-22 GET /api/v1/prevail/appointments?updated_since=2026-04-01 ``` Use `date_start=YYYY-MM-DD&date_end=YYYY-MM-DD` with the same value for an exact-day appointment filter. Appointment date filters match records whose start/end date range overlaps the requested range. Blank or whitespace appointment query filter values intentionally mean no filter and are treated as omitted. Unsupported appointment query fields still return `422`, even when blank. Use `matter_id` as the matter filter on firm-level document, ledger, payment, trust payment, trust deposit, medical record, employment record, disability, process, SMS message, damage, lien, negotiation, evidence, task, and appointment list endpoints. Path values and response fields may use Prevail's `matterid` name. The Process, SMS Messages, Disability, Damages, Liens, Negotiations, Payments, Trust Payments, and Trust Deposits firm-level lists accept both `matter_id` and `matterid`; matter-scoped Process, SMS Messages, Disability, Damages, Liens, Negotiations, Payments, Trust Payments, and Trust Deposits routes use the path `matterid` and do not accept matter filters. The legacy `matterid` request field is still accepted where it existed before for compatibility, but new integrations should send `matter_id`. ## Pagination Pagination support is implemented per list endpoint. The endpoint reference is authoritative for whether an endpoint accepts `page` and `limit`. When an endpoint accepts `page`, page numbers start at `1`; `page=0` is rejected. When an endpoint accepts `limit`, the value must be at least `1`. Many list endpoints enforce a maximum `limit` of `100`, but older list endpoints only validate that `limit` is a positive integer. The API does not calculate one global default `page`, `limit`, or `has_more` before forwarding requests to the connected Prevail system. Examples commonly show `page: 1`, `limit: 50`, and `has_more: false`; treat those as endpoint examples, not a guarantee that every list response has identical pagination metadata. Client paging recommendation: request `page=1` with an explicit `limit` where the endpoint supports it. When `pagination.has_more` is present, continue requesting pages until `has_more` is false. If `has_more` or the `pagination` object is absent, do not infer another page from collection size alone; use the endpoint reference and the returned metadata for that endpoint. ### Recommended Paging Loop 1. Start with `page=1` and a supported `limit`. 2. Process all records in the returned collection. 3. If `pagination.has_more` is `true`, increment `page` and repeat the request. 4. If `pagination.has_more` is `false`, stop. 5. If pagination metadata is absent, follow that endpoint's reference example instead of assuming a global paging contract. ## Sorting Sort support is endpoint-specific. Contact list endpoints document a `sort` query parameter with supported fields and an optional leading `-` for descending order. Unless an endpoint documents a sort parameter, response order is not guaranteed. Do not rely on list order for synchronization. Use endpoint-specific date filters, `updated_since` where available, and stable record IDs to track changes. ## Incremental Sync Use `updated_since=YYYY-MM-DD` only on list endpoints that document it. Current list resources that document `updated_since` include Contacts, Ledger, Payments, Trust Payments, Trust Deposits, Medical, History, Employment, Disability, Process, SMS Messages, Damages, Liens, Negotiations, Evidence, Tasks, and Appointments. Check the endpoint reference for the exact firm-level or matter-scoped route. Endpoint descriptions define `updated_since` inclusively, using records updated, created, or modified on or after the supplied date. The request value is a date only, not a timestamp, and the API validates it as `YYYY-MM-DD` before forwarding it to the connected Prevail system. The exact Prevail field used for comparison is endpoint-specific and is not defined by a global API contract. Because `updated_since` is date-only and inclusive, sync clients should store the last successful sync date, query from that date again on the next run, page through all returned results, and deduplicate records by stable record ID plus `modified` when the endpoint returns it. Some endpoint examples do not include `modified` or `created`; for those endpoints, deduplicate by stable record ID and the endpoint-specific fields your integration stores. Deleted records are not returned as tombstones in V1 unless an endpoint explicitly says otherwise. For appointments, private and deleted appointments are omitted; cancelled non-deleted appointments remain visible with status `Cancelled`. This overview does not define whether cancellation changes the appointment field used by `updated_since`. ## Webhooks and Polling V1 does not currently expose webhook delivery, callback registration, or public event payload schemas for external integrations. Internal API callbacks and signed document handoff routes are not customer webhook subscriptions. For sync jobs, poll list endpoints with endpoint-specific date filters or `updated_since` where supported. Deleted records are not emitted as tombstones unless an endpoint explicitly documents otherwise. ## Resources The Prevail API is organized by resource types listed below. ### Common Starting Points | If You Need To... | Start Here | Why | |---|---|---| | Identify the matter | Matters | Most matter-scoped endpoints need `matterid` or `matter_id`. | | Identify a person, company, or provider | Contacts | Contact IDs are reused by matter links, providers, lienholders, and communication records. | | Upload, download, or replace files | Documents | File operations are handled by document endpoints, not by metadata-only resources. | | Use firm-specific categories or subjects | Lookups | Lookup values must match the firm's Prevail configuration exactly. | | Work with calendar activity | Appointments | Appointment status transitions use dedicated cancel and reschedule endpoints. | | Work with financial activity | Ledger, Payments, Trust Payments, Trust Deposits | Financial resources have separate category, subject, and idempotency rules. | | Add notes or metadata | Medical, History, Damages, Liens, Negotiations, Evidence | These endpoints create or update metadata; use document endpoints when a file is involved. | When an endpoint accepts a lookup value such as `category`, `subject`, `type`, `location`, or `assigned_to`, fetch the relevant lookup list first and send the value exactly as returned. ### Full Resource Catalog | Resource | Base Path | Read/Write Support | File Support | Primary Response Key | Notes | |---|---|---|---|---|---| | Matters | `/matters` | List, detail, create, update | No file content | `matters`, `matter`, `matterid` | Supported actions are listed in the API reference. | | Prospects | `/prospects` | List, detail, create, update | No file content | `prospects`, `prospect`, `matterid` | Supported actions are listed in the API reference. | | Contacts | `/contacts` | List, detail, create, update; communication, address, and matter-contact operations | No file content | `contacts`, `contact`, `communication`, `address`, `matter_contact` | Contact IDs are reused by related resources. | | Documents | `/documents` | List, detail, metadata update, upload, download, file replacement | Upload, download, and replace document files | `documents`, `document` | Use document endpoints for document/file operations. | | Ledger | `/ledger` and `/matters/{matterid}/ledger` | List, detail, create, update | No file content | `ledger_entries`, `ledger_entry` | Matter-scoped creates use the path matter ID. | | Payments | `/payments` and `/matters/{matterid}/payments` | List, detail, create, update | No file content | `payments`, `payment` | Matter-scoped creates use the path matter ID. | | Trust Payments | `/trust-payments` and `/matters/{matterid}/trust-payments` | List, detail, create, update | No file content | `trust_payments`, `trust_payment` | Matter-scoped creates use the path matter ID. | | Trust Deposits | `/trust-deposits` and `/matters/{matterid}/trust-deposits` | List, detail, create, update | No file content | `trust_deposits`, `trust_deposit` | Matter-scoped creates use the path matter ID. | | Medical | `/medical` and `/matters/{matterid}/medical` | List, detail, create, update | Metadata only | `medical_records`, `medical_record` | Stores medical record metadata only. | | History | `/history` and `/matters/{matterid}/history` | List, detail, create, update | Metadata only | `history_records`, `history_record` | Ordinary matter history records. | | Employment | `/employment` and `/matters/{matterid}/employment` | Read-only list and detail | No file content | `employment_records`, `employment_record` | Does not create, update, or delete employment records. | | Disability | `/disability` and `/matters/{matterid}/disability` | Read-only list and detail | No file content | `disability_records`, `disability_record` | Does not create, update, or delete disability records. | | Process | `/processes` and `/matters/{matterid}/processes` | Read-only list and detail | No file content | `process_records`, `process_record` | Also referred to as claims process records. | | SMS Messages | `/sms-messages` and `/matters/{matterid}/sms-messages` | Read-only list and detail | No file content | `sms_messages`, `sms_message` | Does not send messages or mark inbound messages as retrieved. | | Damages | `/damages` and `/matters/{matterid}/damages` | List, detail, create, update | Metadata only | `damage_records`, `damage_record` | Use document endpoints when a file attachment is required. | | Liens | `/liens` and `/matters/{matterid}/liens` | List, detail, create, update | Metadata only | `lien_records`, `lien_record` | Does not manage release, payoff, trust/accounting, settlement negotiation, or bulk workflows. | | Negotiations | `/negotiations` and `/matters/{matterid}/negotiations` | List, detail, create, update | Metadata only | `negotiation_records`, `negotiation_record` | Does not finalize settlements, run calculators, or trigger lien, payment, or trust side effects. | | Evidence | `/evidence` and `/matters/{matterid}/evidence` | List, detail, create, update | Metadata only | `evidence_records`, `evidence_record` | Use document endpoints when a file attachment is required. | | Tasks | `/tasks` | List, detail, create, update, complete, reopen | No file content | `tasks`, `task` | Complete and reopen are workflow transitions. | | Appointments | `/appointments` | List, detail, create, update, cancel, reschedule | No file content | `appointments`, `appointment` | Use action endpoints for status transitions. | | Lookups | `/lookups` | Read-only lookup lists | No file content | Lookup-specific collection keys | Firm-specific values for request fields. | ### Metadata-only Resources The resources below create, update, or return Prevail record metadata only. They do not upload, download, replace, or stream file content. Use document endpoints for document/file operations. | Resource | Metadata Covered | Important Exclusions | |---|---|---| | Medical | Medical record history entries and medical record details. | Stores medical record metadata only; use document endpoints for attached medical files. | | History | Ordinary matter history notes and history details. | Excludes document attachments and medical record workflows. | | Damages | Damage records and damage details. | Does not upload, download, or replace damage files; use document endpoints for attachments. | | Liens | Lien records and lien details. | Does not handle lien documents, release, payoff, trust/accounting, settlement negotiation, or bulk workflows. | | Negotiations | Negotiation records and negotiation details. | Does not finalize settlements, run calculators, manage files, or trigger lien, payment, or trust accounting side effects. | | Evidence | Evidence records and evidence details. | Does not upload, download, or replace evidence files; use document endpoints for attachments. | ## Resource Endpoint Summaries Document endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/documents` | Query parameters | List document records. Supports `matter_id`, `category`, `filename`, `search`, `limit`, and `page`. | | `GET` | `/documents/{document_id}` | None | Retrieve one document record by opaque `document_id`. | | `GET` | `/documents/{document_id}/file` | None | Download the stored document file by opaque `document_id`. | | `POST` | `/matters/{matterid}/documents` | `multipart/form-data` | Upload a new document file to the matter in the path. Body `matter_id`, when sent, must match the path. | | `PATCH` | `/documents/{document_id}` | JSON | Update document details only. This does not replace the stored file. Send at least one field. | | `POST` | `/documents/{document_id}/file` | `multipart/form-data` | Replace an existing document file and optionally update document details. | Ledger endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/ledger` | Query parameters | List ledger entries. Expected filters include `matter_id`, `type`, `category`, `subject`, `search`, `entry_date_start`, `entry_date_end`, `updated_since`, `amount_min`, `amount_max`, `limit`, and `page`. | | `GET` | `/ledger/{ledger_id}` | None | Retrieve one ledger entry by opaque `ledger_id`. | | `GET` | `/matters/{matterid}/ledger` | Query parameters | List ledger entries for a specific matter. | | `POST` | `/matters/{matterid}/ledger` | JSON | Create a ledger entry for the matter in the path. | | `PATCH` | `/ledger/{ledger_id}` | JSON | Update ledger entry details. Send at least one supported field. | Payment endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/payments` | Query parameters | List payment records. Expected filters include `matter_id`, `category`, `subject`, `status`, `search`, `payment_date_start`, `payment_date_end`, `updated_since`, `amount_min`, `amount_max`, `limit`, and `page`. | | `GET` | `/payments/{payment_id}` | None | Retrieve one payment record by opaque `payment_id`. | | `GET` | `/matters/{matterid}/payments` | Query parameters | List payment records for a specific matter. | | `POST` | `/matters/{matterid}/payments` | JSON | Create a payment record for the matter in the path. | | `PATCH` | `/payments/{payment_id}` | JSON | Update payment details. Send at least one supported field. | Trust payment endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/trust-payments` | Query parameters | List trust payment records. Expected filters include `matter_id`, `category`, `subject`, `status`, `search`, `payment_date_start`, `payment_date_end`, `updated_since`, `amount_min`, `amount_max`, `limit`, and `page`. | | `GET` | `/trust-payments/{trust_payment_id}` | None | Retrieve one trust payment record by opaque `trust_payment_id`. | | `GET` | `/matters/{matterid}/trust-payments` | Query parameters | List trust payment records for a specific matter. | | `POST` | `/matters/{matterid}/trust-payments` | JSON | Create a trust payment record for the matter in the path. Requires `category`, `subject`, `payment_date`, `amount`, and `idempotency_key`. | | `PATCH` | `/trust-payments/{trust_payment_id}` | JSON | Update trust payment details. Send at least one supported field. | Trust deposit endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/trust-deposits` | Query parameters | List trust deposit records. Expected filters include `matter_id`, `category`, `subject`, `status`, `search`, `deposit_date_start`, `deposit_date_end`, `updated_since`, `amount_min`, `amount_max`, `limit`, and `page`. | | `GET` | `/trust-deposits/{trust_deposit_id}` | None | Retrieve one trust deposit record by opaque `trust_deposit_id`. | | `GET` | `/matters/{matterid}/trust-deposits` | Query parameters | List trust deposit records for a specific matter. | | `POST` | `/matters/{matterid}/trust-deposits` | JSON | Create a trust deposit record for the matter in the path. Requires `category`, `subject`, `deposit_date`, `amount`, and `idempotency_key`. | | `PATCH` | `/trust-deposits/{trust_deposit_id}` | JSON | Update trust deposit details. Send at least one supported field. | Medical endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/medical` | Query parameters | List Prevail medical record history entries. Expected filters include `matter_id`, `record_type`, `status`, `provider_contact_id`, `provider_name`, `ailment`, `icd_code`, `search`, `from_date_start`, `from_date_end`, `received_date_start`, `received_date_end`, `date_start`, `date_end`, `updated_since`, `limit`, and `page`. | | `GET` | `/medical/{medical_record_id}` | None | Retrieve one medical record by opaque `medical_record_id`. | | `GET` | `/matters/{matterid}/medical` | Query parameters | List medical records for a specific matter. | | `POST` | `/matters/{matterid}/medical` | JSON | Create a medical record history entry for the matter in the path. | | `PATCH` | `/medical/{medical_record_id}` | JSON | Update medical record details. Send at least one supported field. | History endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/history` | Query parameters | List ordinary metadata-only history records. Expected filters include `matter_id`, `matterid`, `type`, `category`, `subject`, `author`, `search`, `date_start`, `date_end`, `updated_since`, `limit`, and `page`. Successful responses use the `history_records` key. | | `GET` | `/history/{history_id}` | None | Retrieve one ordinary history record by opaque `history_id`. Successful responses use the `history_record` key. | | `GET` | `/matters/{matterid}/history` | Query parameters | List ordinary history records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `history_records` key. | | `POST` | `/matters/{matterid}/history` | JSON | Create an ordinary history record for the matter in the path. Send at least `subject` or `notes`. There is no history file upload endpoint. | | `PATCH` | `/history/{history_id}` | JSON | Update ordinary history metadata details. Send at least one supported field. There is no history file replacement endpoint. | Employment endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/employment` | Query parameters | List Prevail employment history records. Expected filters include `matter_id`, `employer_contact_id`, `contact_id`, `employer_name`, `job_title`, `employment_status`, `status`, `is_current`, `search`, `start_date_start`, `start_date_end`, `end_date_start`, `end_date_end`, `updated_since`, `limit`, and `page`. Successful responses use the `employment_records` key. | | `GET` | `/employment/{employment_record_id}` | None | Retrieve one employment record by opaque `employment_record_id`. Successful responses use the `employment_record` key. | | `GET` | `/matters/{matterid}/employment` | Query parameters | List employment records for a specific matter. Successful responses use the `employment_records` key. | Disability endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/disability` | Query parameters | List read-only disability/ailment records. Expected filters include `matter_id`, `matterid`, `claimant_contact_id`, `contact_id`, `ailment`, `duration`, `severity`, `workload`, `search`, `created_start`, `created_end`, `updated_since`, `limit`, and `page`. Successful responses use the `disability_records` key. | | `GET` | `/disability/{disability_id}` | None | Retrieve one read-only disability/ailment record by opaque `disability_id`. Successful responses use the `disability_record` key. | | `GET` | `/matters/{matterid}/disability` | Query parameters | List read-only disability/ailment records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `disability_records` key. | Process endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/processes` | Query parameters | List read-only process records, also referred to as claims process records. Expected filters include `matter_id`, `matterid`, `type`, `process_type`, `subject`, `process_name`, `status`, `stage`, native process date filters, `search`, `updated_since`, `limit`, and `page`. Successful responses use the `process_records` key. | | `GET` | `/processes/{process_id}` | None | Retrieve one read-only process record by opaque `process_id`. Successful responses use the `process_record` key. | | `GET` | `/matters/{matterid}/processes` | Query parameters | List read-only process records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `process_records` key. | SMS message endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/sms-messages` | Query parameters | List read-only SMS message records. Expected filters include `matter_id`, `matterid`, `direction`, `from_phone`, `to_phone`, `phone`, `status`, `search`, SMS date filters, `updated_since`, `limit`, and `page`. Successful responses use the `sms_messages` key. | | `GET` | `/sms-messages/{sms_message_id}` | None | Retrieve one read-only SMS message record by opaque `sms_message_id`. Successful responses use the `sms_message` key. | | `GET` | `/matters/{matterid}/sms-messages` | Query parameters | List read-only SMS message records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `sms_messages` key. | Damages endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/damages` | Query parameters | List damage metadata records. Expected filters include `matter_id`, `matterid`, `type`, `subject`, `status`, `search`, `damage_date_start`, `damage_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`, `limit`, and `page`. Successful responses use the `damage_records` key. | | `GET` | `/damages/{damage_id}` | None | Retrieve one damage metadata record by opaque `damage_id`. Successful responses use the `damage_record` key. | | `GET` | `/matters/{matterid}/damages` | Query parameters | List damage metadata records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `damage_records` key. | | `POST` | `/matters/{matterid}/damages` | JSON | Create damage metadata for the matter in the path. There is no damage file upload endpoint. | | `PATCH` | `/damages/{damage_id}` | JSON | Update damage metadata details. Send at least one supported field. There is no damage file replacement endpoint. | Liens endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/liens` | Query parameters | List metadata-only lien records. Expected filters include `matter_id`, `matterid`, `subject`, `policy_number`, `client_contact_id`, `lienholder_contact_id`, `provider_contact_id`, `lien_date_start`, `lien_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`, `insured_amount_min`, `insured_amount_max`, `notice`, `include_in_settlement_calculator`, `search`, `limit`, and `page`. Successful responses use the `lien_records` key. | | `GET` | `/liens/{lien_id}` | None | Retrieve one metadata-only lien record by opaque `lien_id`. Successful responses use the `lien_record` key. | | `GET` | `/matters/{matterid}/liens` | Query parameters | List metadata-only lien records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `lien_records` key. | | `POST` | `/matters/{matterid}/liens` | JSON | Create lien metadata for the matter in the path. Requires `subject`; optional fields include `policy_number`, `amount`, `insured_amount`, contact IDs, notes, and boolean flags. There is no lien file upload endpoint. | | `PATCH` | `/liens/{lien_id}` | JSON | Update lien metadata details. Send at least one supported field. There is no lien file replacement, release, payoff, trust/accounting, settlement negotiation, or bulk endpoint. | Negotiations endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/negotiations` | Query parameters | List metadata-only negotiation records. Expected filters include `matter_id`, `matterid`, `type`, `subject`, `final`, `search`, `negotiation_date_start`, `negotiation_date_end`, `date_start`, `date_end`, `updated_since`, `amount_min`, `amount_max`, `percent_min`, `percent_max`, `alternate_settlement_calculator`, `include_damages_in_settlement_calculator`, `limit`, and `page`. Successful responses use the `negotiation_records` key. | | `GET` | `/negotiations/{negotiation_id}` | None | Retrieve one metadata-only negotiation record by opaque `negotiation_id`. Successful responses use the `negotiation_record` key. | | `GET` | `/matters/{matterid}/negotiations` | Query parameters | List metadata-only negotiation records for a specific matter. Matter filters are not accepted on this matter-scoped route. Successful responses use the `negotiation_records` key. | | `POST` | `/matters/{matterid}/negotiations` | JSON | Create negotiation metadata for the matter in the path. Requires `type`, `subject`, and `idempotency_key`; optional fields include `negotiation_date`, `date`, `amount`, `percent`, and `notes`. There is no settlement finalization or calculator execution endpoint. | | `PATCH` | `/negotiations/{negotiation_id}` | JSON | Update negotiation metadata details. Send at least one supported field. There is no delete, bulk, file, settlement finalization, calculator execution, lien/payment, or trust/accounting endpoint. | Evidence endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/evidence` | Query parameters | List evidence metadata records. Expected filters include `matter_id`, `category`, `subject`, `search`, `date_start`, `date_end`, `updated_since`, `limit`, and `page`. Successful responses use the `evidence_records` key. | | `GET` | `/evidence/{evidence_id}` | None | Retrieve one evidence metadata record by opaque `evidence_id`. Successful responses use the `evidence_record` key. | | `GET` | `/matters/{matterid}/evidence` | Query parameters | List evidence metadata records for a specific matter. Successful responses use the `evidence_records` key. | | `POST` | `/matters/{matterid}/evidence` | JSON | Create an evidence metadata record for the matter in the path. There is no evidence file upload endpoint. | | `PATCH` | `/evidence/{evidence_id}` | JSON | Update evidence metadata details. Send at least one supported field. There is no evidence file replacement endpoint. | Task endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/tasks` | Query parameters | List task records. Supports `matter_id`, `assigned_to`, `status`, `type`, `subject`, `search`, due date filters, `updated_since`, `limit`, and `page`. | | `GET` | `/tasks/{task_id}` | None | Retrieve one task record by opaque `task_id`. | | `GET` | `/matters/{matterid}/tasks` | Query parameters | List task records for a specific matter. | | `POST` | `/matters/{matterid}/tasks` | JSON | Create a task for the matter in the path. | | `PATCH` | `/tasks/{task_id}` | JSON | Update task details. Send at least one supported field. | | `POST` | `/tasks/{task_id}/complete` | JSON | Mark a task complete. | | `POST` | `/tasks/{task_id}/reopen` | JSON | Reopen a completed task. | Appointment endpoint summary: | Method | Endpoint | Body Type | Purpose | |---|---|---|---| | `GET` | `/appointments` | Query parameters | List appointment records. Supports `matter_id`, `assigned_to`, `status`, `type`, `subject`, `location`, `search`, `date_start`, `date_end`, `updated_since`, `limit`, and `page`. | | `GET` | `/appointments/{appointment_id}` | None | Retrieve one appointment record by opaque appointment ID. | | `GET` | `/matters/{matterid}/appointments` | Query parameters | List appointment records for a specific matter. | | `POST` | `/matters/{matterid}/appointments` | JSON | Create an appointment for the matter in the path. Requires `subject`, `date`, and `start_time`. | | `PATCH` | `/appointments/{appointment_id}` | JSON | Update appointment details. Send at least one supported nonblank field. | | `POST` | `/appointments/{appointment_id}/cancel` | JSON | Cancel an appointment. Body may be empty; optional fields are `cancelled_by` and `notes`. | | `POST` | `/appointments/{appointment_id}/reschedule` | JSON | Reschedule an appointment. Requires `date` and `start_time`; optional fields are `end_date`, `end_time`, `assigned_to`, `location`, `notes`, and `rescheduled_by`. | ## Create and Update Requests For create requests, include all fields required by the endpoint. For update requests, send only the fields that should be changed unless the endpoint documents otherwise. Do not send blank strings or `null` values unless the endpoint specifically allows clearing that field. Shared write rules: | Rule | Applies To | |---|---| | Matter-scoped creates use the `{matterid}` path value as the authoritative matter. If a body `matter_id` is allowed and sent, it must match the path value. | Matter-scoped create endpoints. | | Update endpoints generally require at least one supported nonblank field. | `PATCH` update endpoints, except endpoints that document a different action contract. | | Metadata-only resources create or update Prevail records but do not handle file content. Use document endpoints when a file attachment is required. | Medical, History, Damages, Liens, Negotiations, and Evidence; see [Metadata-only Resources](#metadata-only-resources). | | Lookup-backed fields must match firm-specific Prevail lookup values exactly. | Fields such as `type`, `category`, `subject`, `status`, `location`, `assigned_to`, and configured contact values. | Create/update support at a glance: | Resource | V1 write support | |---|---| | Matters | Create and update. | | Prospects | Create and update. | | Contacts | Create and update contacts, matter links, communications, and addresses. | | Documents | Upload, metadata update, file replacement, and download. | | History | Create and update metadata records. | | Ledger | Create and update ledger entries. | | Payments | Create and update payment records. | | Trust Payments | Create and update trust payment records. | | Trust Deposits | Create and update trust deposit records. | | Medical | Create and update medical metadata records. | | Employment | Read-only in V1. | | Disability | Read-only in V1. | | Process | Read-only in V1. | | SMS Messages | Read-only in V1. | | Damages | Create and update metadata records. | | Liens | Create and update metadata records. | | Negotiations | Create and update metadata records. | | Evidence | Create and update metadata records. | | Tasks | Create and update tasks; complete and reopen actions are separate workflow endpoints. | | Appointments | Create and update appointments; cancel and reschedule actions are separate workflow endpoints. | ### Matters Matter create requests require `title`, `lawtype`, `casetype`, and `securitygroup`. Matter create and update requests automatically create or update matter records, not prospect records, and the API sets the required matter status fields for you. ### Prospects Prospect endpoints are for intake or pre-matter records. Use `POST /prospects` to create a prospect; required fields are `title`, `lawtype`, `casetype`, and `securitygroup`. Use `PATCH /prospects/{matterid}` to update a prospect; supported fields include the prospect fields documented in the endpoint reference, such as title, status, dates, staff assignments, notes, location fields, boolean flags, and `custom_fields`. Prospect create and update responses return the prospect's Prevail matter identifier as top-level `matterid`. ### Contacts Contact create requests require `type` and at least one identity field: `first_name`, `last_name`, or `company_name`. Optional identity fields such as `middle_name` are passed through to Prevail when sent. The optional `ssn` field can be set or cleared by contact create and update requests. The full SSN is returned only by authenticated `GET /contacts/{contact_id}`; contact lists and write responses omit it. Contact address data can be sent either as a nested `address` object or as flat address fields on the contact request. Matter-contact links are created with `POST /matters/{matterid}/contacts` and require `contact_id`. Optional `role`, `type`, and `notes` fields describe the contact's relationship to that matter. Contact communication records require `category` and `value` when created. Optional boolean fields such as `primary`, `international`, and `messages` accept JSON booleans or the strings `"true"` and `"false"`. Contact address records use `address_type` values of `physical` or `mailing`. Creating an address requires `address_type` and `address_1`; updating an address uses the address type in the path and requires at least one address field in the request body. ### Documents Document creation uses `multipart/form-data` and requires an uploaded file. Create a document by sending `POST /matters/{matterid}/documents`, where the path `matterid` is authoritative. If the request body includes `matter_id`, it must match the path value. Send the uploaded file in the `file` field; `document` is accepted as an alias. File uploads for document creation and replacement are limited to 50 MB and allow these extensions: `pdf`, `doc`, `docx`, `txt`, `rtf`, `jpg`, `jpeg`, `png`, `tif`, `tiff`, `bmp`, `xls`, `xlsx`, and `wpd`. Optional document metadata fields are `filename`, `category`, `subject`, `notes`, `date`, `time`, and `author`. Metadata length limits are: `category` 30 characters, `subject` 200 characters, and `author` 25 characters. If `filename` is omitted during upload, the API uses the uploaded file name. If `filename` is sent, it must use the same extension as the uploaded file. The legacy `document_date` field is accepted as an alias for `date`. Example document upload: ```bash curl --request POST "/matters//documents" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " \ --form "file=@/path/to/provider-summary.pdf" \ --form "matter_id=" \ --form "filename=provider-summary.pdf" \ --form "category=Medical Records" \ --form "subject=Provider records" \ --form "date=2026-04-22" \ --form "author=KIM" ``` The document API does not create document records without an attached file. Use a note or history workflow for entries that do not have an attached file. Document detail update requests use `PATCH /documents/{document_id}` and accept `category`, `subject`, `notes`, `author`, `date`, and `time`. This endpoint does not change the attachment filename or replace the stored file. Treat `document_id` as an opaque value returned by document list, upload, update, or file replacement responses. Document file downloads use `GET /documents/{document_id}/file`. Successful responses return the raw file body with `Content-Disposition`, `Content-Type`, and `Content-Length` headers when file metadata is available. Authentication still uses the same credential headers. Download error responses return JSON with `error_message`. The connected Prevail system must be available before the API can stream the file to the caller. Document file replacement uses `multipart/form-data` at `POST /documents/{document_id}/file`. Send the replacement file in the `file` field; `document` is accepted as an alias. Replacement requests may also include the same optional document metadata fields as update requests. The same file size, extension, filename, and metadata limits apply. Example document file replacement: ```bash curl --request POST "/documents//file" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " \ --form "file=@/path/to/provider-summary-updated.pdf" \ --form "filename=provider-summary-updated.pdf" \ --form "category=Medical Records" \ --form "date=2026-04-22" \ --form "author=KIM" ``` Document upload and replacement endpoints require `multipart/form-data`; they do not accept raw file content in JSON, such as base64 payloads or external file URLs. ### History History creation uses `POST /matters/{matterid}/history`. Create requests require at least one of `subject` or `notes`; optional fields are `type`, `category`, `date`, `time`, and `author`. If omitted, the connected Prevail system defaults `type`, `date`, `time`, and `author`. History detail updates use `PATCH /history/{history_id}` and update only the documented fields sent in the request body. Treat `history_id` as an opaque value returned by history list, detail, create, or update responses. History responses use `history_records` for lists and `history_record` for single-record, create, and update responses. ### Ledger Ledger creation uses `POST /matters/{matterid}/ledger`. Create requests require `type`, `category`, `subject`, `entry_date`, and `amount` unless `type` is `Time`. Optional fields are `notes`, `hours`, and `rate`. Expected lookup-backed fields include `type`, `category`, and `subject`; use the ledger lookup endpoints to select valid values before sending a ledger request. Ledger detail updates use `PATCH /ledger/{ledger_id}` and update only the documented fields sent in the request body. Treat `ledger_id` as an opaque value returned by ledger list, detail, create, or update responses. ### Payments Payment creation uses `POST /matters/{matterid}/payments`. Create requests require `category`, `subject`, `payment_date`, and a non-negative `amount`. Optional fields are `status`, `reference`, `notes`, `document_id`, `contact_id`, and `assigned_to`. Expected lookup-backed fields include `category` and `subject`; use the payment lookup endpoints to select valid values before sending a payment request. Payment detail updates use `PATCH /payments/{payment_id}` and update only the documented fields sent in the request body. Treat `payment_id` as an opaque value returned by payment list, detail, create, or update responses. Regular payment endpoints are separate from trust payment lookups and do not manage trust-accounting payments. ### Trust Payments Trust payment creation uses `POST /matters/{matterid}/trust-payments`. Create requests require `category`, `subject`, `payment_date`, a non-negative `amount`, and `idempotency_key`. Optional fields are `status`, `reference`, `notes`, `document_id`, `contact_id`, and `assigned_to`. Expected lookup-backed fields include `category` and `subject`; use the trust payment lookup endpoints to select valid values before sending a trust payment request. The API validates and forwards `idempotency_key`; the connected Prevail system enforces trust balance, reconciliation, and duplicate-retry rules. Trust payment detail updates use `PATCH /trust-payments/{trust_payment_id}` and update only the documented fields sent in the request body. Treat `trust_payment_id` as an opaque value returned by trust payment list, detail, create, or update responses. `idempotency_key` is accepted only on create requests. ### Trust Deposits Trust deposit creation uses `POST /matters/{matterid}/trust-deposits`. Create requests require `category`, `subject`, `deposit_date`, a non-negative `amount`, and `idempotency_key`. Optional fields are `status`, `reference`, `notes`, `document_id`, `contact_id`, and `assigned_to`. Expected lookup-backed fields include `category` and `subject`; use the trust deposit lookup endpoints to select valid values before sending a trust deposit request. The API validates and forwards `idempotency_key`; the connected Prevail system enforces trust balance, reconciliation, and duplicate-retry rules. Trust deposit detail updates use `PATCH /trust-deposits/{trust_deposit_id}` and update only the documented fields sent in the request body. Treat `trust_deposit_id` as an opaque value returned by trust deposit list, detail, create, or update responses. `idempotency_key` is accepted only on create requests. ### Medical Medical record creation uses `POST /matters/{matterid}/medical`. Create requests require `record_type` and one of `provider_contact_id` or `provider_name`. The `record_type` field accepts only `Medical Record`, `Medical`, `Medical Rqstd`, or `Medical Rcvd`. Optional fields are `status`, `ailment`, `icd_code`, `from_date`, `to_date`, `requested_date`, `received_date`, `summary`, `notes`, `document_id`, and `assigned_to`. Medical record detail updates use `PATCH /medical/{medical_record_id}` and update only the documented fields sent in the request body. Treat `medical_record_id` as an opaque value returned by medical record list, detail, create, or update responses. ### Employment Employment record endpoints are read-only. Use `GET /employment` for firm-level lists, `GET /matters/{matterid}/employment` for matter-scoped lists, and `GET /employment/{employment_record_id}` for one record. There are no V1 employment record create, update, delete, or file endpoints. Employment record responses use `employment_records` for lists and `employment_record` for single-record details. ### Disability Disability endpoints are read-only. Use `GET /disability` for firm-level lists, `GET /matters/{matterid}/disability` for matter-scoped lists, and `GET /disability/{disability_id}` for one record. There are no V1 disability create, update, delete, file, or bulk endpoints. Disability responses use `disability_records` for lists and `disability_record` for single-record details. ### Process Process endpoints are read-only. Use `GET /processes` for firm-level lists, `GET /matters/{matterid}/processes` for matter-scoped lists, and `GET /processes/{process_id}` for one record. These endpoints expose Prevail process records, also referred to as claims process records. There are no V1 process create, update, delete, file, status mutation, or bulk endpoints. Process responses use `process_records` for lists and `process_record` for single-record details. ### SMS Messages SMS message endpoints are read-only. Use `GET /sms-messages` for firm-level lists, `GET /matters/{matterid}/sms-messages` for matter-scoped lists, and `GET /sms-messages/{sms_message_id}` for one record. There are no V1 SMS message create, send, update, retrieve-state mutation, delete, attachment, or bulk endpoints. SMS responses use `sms_messages` for lists and `sms_message` for single-record details. ### Damages Damage creation uses `POST /matters/{matterid}/damages`. Damage responses use `damage_records` for lists and `damage_record` for single-record, create, and update responses. Damage detail updates use `PATCH /damages/{damage_id}` and update only the documented fields sent in the request body. Treat `damage_id` as an opaque value returned by damage list, detail, create, or update responses. ### Liens Lien creation uses `POST /matters/{matterid}/liens`. Create requests require only `subject`. Optional `amount` and `insured_amount` default to `0`, boolean fields default to `false`, and `lien_date` uses Prevail database behavior when omitted. `policy_number` is limited to 20 characters. Lien responses use `lien_records` for lists and `lien_record` for single-record, create, and update responses. Lien detail updates use `PATCH /liens/{lien_id}` and update only the documented fields sent in the request body. Treat `lien_id` as an opaque value returned by lien list, detail, create, or update responses. Send `lienholder_contact_id` as the canonical lienholder contact field; `provider_contact_id` is accepted as an alias, but the API rejects requests where both fields are present with different values. ### Negotiations Negotiation creation uses `POST /matters/{matterid}/negotiations`. Create requests require `type`, `subject`, and `idempotency_key`. `type` accepts only `Demand` or `Offer`; `subject` should be selected from the negotiation subject lookup. Optional fields are `negotiation_date`, `date` as an alias for `negotiation_date`, `amount`, `percent`, and `notes`. The API validates and forwards `idempotency_key` on create requests only; duplicate-retry detection is performed by the connected Prevail system. Negotiation detail updates use `PATCH /negotiations/{negotiation_id}` and update only the documented fields sent in the request body. Treat `negotiation_id` as an opaque value returned by negotiation list, detail, create, or update responses. `final`, `alternate_settlement_calculator`, and `include_damages_in_settlement_calculator` are response/filter metadata only in V1, and the internal `linkid` field is never accepted or returned by the public API. ### Evidence Evidence creation uses `POST /matters/{matterid}/evidence`. Evidence responses use `evidence_records` for lists and `evidence_record` for single-record, create, and update responses. Evidence detail updates use `PATCH /evidence/{evidence_id}` and update only the documented fields sent in the request body. Treat `evidence_id` as an opaque value returned by evidence list, detail, create, or update responses. ### Tasks Task creation uses `POST /matters/{matterid}/tasks` and requires `subject`. Optional task workflow fields are `type`, `due_date`, `assigned_to`, `status`, `notes`, and `reminder_at`. A minimal task create request can send only `subject`; use task lookup values for optional fields such as `type` when your integration sends them. Task detail updates use `PATCH /tasks/{task_id}` and require at least one supported field. Use `POST /tasks/{task_id}/complete` when callers need to provide explicit `completed_at` or `completed_by` values. The generic update endpoint does not accept `completed`, `completed_at`, or `completed_by`. Task completion and reopen actions accept optional workflow fields documented on those endpoints. Example task creation: ```bash curl --request POST "/matters//tasks" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " \ --header "Idempotency-Key: task--20260422-001" \ --data '{ "subject": "Follow up with client" }' ``` ### Appointments Appointment creation uses `POST /matters/{matterid}/appointments`. Create requests require `subject`, `date`, and `start_time`. If `end_date` is omitted, it defaults to `date`. If `end_time` is omitted, the API defaults it to `start_time` plus 30 minutes only when that calculated end time remains on the same date; otherwise the API returns `422` before processing the request. Optional appointment fields are `type`, `end_date`, `end_time`, `assigned_to`, `notes`, and `location`. Appointment date, end_date, start_time, and end_time request and response fields are firm-local values. Use `end_date` for multi-day appointments. When updating an existing multi-day appointment, changing `date` without sending `end_date` preserves the existing date span; send both `date` and `end_date` when changing the full range. type, subject, and location are lookup-backed fields: use appointment types, appointment subjects, and appointment locations respectively. `assigned_to` is the primary appointment attendee in responses. The `assigned_to` filter matches any active attendee on the appointment. Create requests may omit `assigned_to` only when the matter has a valid default attorney or case manager; otherwise Prevail returns `422`. Appointment detail updates use `PATCH /appointments/{appointment_id}` and update only the fields sent in the request body. V1 appointment updates accept `type`, `subject`, `date`, `end_date`, `start_time`, `end_time`, `assigned_to`, `notes`, and `location`. Appointment status is filterable and can be returned in responses as `Scheduled`, `Rescheduled`, or `Cancelled`, but it is response-only on the generic detail update endpoint. Use `POST /appointments/{appointment_id}/cancel` to mark an appointment `Cancelled`. The cancel body may be empty; optional fields are `cancelled_by` and `notes`. Use `POST /appointments/{appointment_id}/reschedule` to move an appointment and mark it `Rescheduled`. Reschedule requests require `date` and `start_time`. If `end_date` is omitted, it defaults to `date`. If `end_time` is omitted, the API defaults it to `start_time` plus 30 minutes only when that calculated end time remains on the same date; otherwise the API returns `422` before processing the request. Optional reschedule fields are `end_date`, `end_time`, `assigned_to`, `location`, `notes`, and `rescheduled_by`. Rescheduling a previously cancelled appointment clears the cancelled state and returns the appointment with status `Rescheduled`. Optional blank, whitespace-only, or `null` appointment fields are treated as omitted for list filters, create, update, cancel, and reschedule requests. Required appointment fields still fail when blank, malformed nonblank values still fail validation, and unsupported appointment fields still return `422` even when their value is blank. Private and deleted appointments are omitted from list responses and return not found for detail or update requests. `updated_since` does not emit deletion tombstones in V1; cancelled non-deleted appointments remain visible with status `Cancelled`. `reminder_at` is returned as null/read-only in V1 and is not accepted in appointment write payloads. Appointment attendee mutation beyond replacing the primary `assigned_to` attendee is not available in V1. ## Idempotency and Safe Retries Read requests such as `GET` are generally safe to retry when a network error, `503`, or `504` occurs. Write requests such as `POST`, `PUT`, and `PATCH` should be retried carefully because the original request may have succeeded even if the client received a timeout. For write requests: - Send an `Idempotency-Key` header on `POST` and `PATCH` requests when you want the API to protect a retry from dispatching the same Prevail write twice. - Reuse the same key only when retrying the same request body, path, query string, and uploaded file content. Reusing a key for a different request returns `409 Conflict`. - If an idempotent write returns `504 Timeout`, retry the same request with the same `Idempotency-Key`; the API will not dispatch a second write while the original result is still unknown. - Successful idempotent retries replay the original JSON response and include `Idempotency-Replayed: true`. - Trust payment, trust deposit, and negotiation create endpoints still require their documented body `idempotency_key` because the connected Prevail system also uses that value for duplicate detection. - Prefer using endpoint-specific reference or identifier fields when the endpoint documents them, so your integration can detect whether a record was already created. - For `PUT` and `PATCH`, retry only when your integration can safely confirm that sending the same update again will not create duplicate data or overwrite newer changes. - Use exponential backoff for retryable errors instead of sending rapid repeated requests. ### How Idempotency Works Use the `Idempotency-Key` header on documented Prevail API `POST` and `PATCH` write endpoints whenever a client may retry a create or update request after a network failure, client timeout, or `504 Timeout` response. Generate one unique key per logical write operation and save that key with the client-side job or transaction until the write is finished. Accepted key characters are letters, numbers, `.`, `_`, `:`, and `-`; the maximum length is 80 characters. Reusing a key for a different write is not allowed. When the first request with a key is accepted for forwarding to Prevail, the Prevail API records an idempotency fingerprint. The fingerprint includes the HTTP method, API path, route parameters, query string, request body, uploaded file names, uploaded file metadata, and uploaded file SHA-256 content hashes. A retry must send the same method, path, query string, body fields, and file content. Changing any of those values while reusing the same `Idempotency-Key` returns `409 Conflict`. Idempotency keys are scoped to the authenticated firm and API key. A key used by one API key cannot be replayed by a different API key, even when both API keys are linked to the same firm. Completed idempotent writes are replayable for the configured idempotency window, `PREVAIL_IDEMPOTENCY_TTL` seconds; the default is `86400` seconds, or 24 hours. A replay does not dispatch another request to the connected Prevail system. Instead, the Prevail API returns the original JSON response body and HTTP status, plus this response header: ```http Idempotency-Replayed: true ``` ### Retry Outcomes | Situation | Response | Client action | |---|---|---| | First request succeeds | Endpoint's normal success status and body | Store the returned record identifier. | | Exact retry after success | Same status and JSON body as the first response, with `Idempotency-Replayed: true` | Treat as the same successful write. | | Same key while the first request is still processing | `409 Conflict` with `Request with this Idempotency-Key is already in progress.` | Wait and retry the exact same request with the same key. | | Same key after the first request timed out and no callback has arrived yet | `504 Timeout` | Keep retrying the exact same request with the same key using backoff; do not send a new key unless you have confirmed the original write did not happen. | | Same key with a different method, path, query string, body, or file content | `409 Conflict` with `Idempotency-Key has already been used for a different request.` | Create a new key only for a genuinely new write. | | Invalid key format | `422 Unprocessable Entity` | Generate a key that matches the documented character and length rules. | Example create request: ```http POST /api/v1/prevail/matters//payments HTTP/1.1 X-Client-ID: X-Client-Secret: Content-Type: application/json Accept: application/json Idempotency-Key: payment--20260702-001 ``` ```json { "category": "Payment", "subject": "Insurance Payment", "status": "Open", "payment_date": "2026-04-22", "amount": "250.00", "reference": "CHK-250" } ``` If the client receives `504 Timeout`, resend the same request body to the same URL with the same `Idempotency-Key`. When the original write later completes, the retry returns the original response with `Idempotency-Replayed: true`. Reuse the same `Idempotency-Key` only when retrying the exact same request. After a `504` on a create request, search for the record using the matter ID, date, subject, amount, reference, or other endpoint-specific filters documented for that resource before sending a new logical create request. For a timed-out payment create, search payments for the matter using `payment_date_start` and `payment_date_end` for the payment date, `category`, `subject`, and `amount_min` plus `amount_max` set to the expected amount. Trust payment, trust deposit, and negotiation create endpoints still require their documented body field named `idempotency_key`. That body field is separate from the `Idempotency-Key` header: the header protects Prevail API safe retries, while the body field is forwarded to the connected Prevail system for its own duplicate detection. ## Rate Limits and Request Volume Prevail API routes do not currently publish a numeric rate limit or guarantee `429 Too Many Requests` / `Retry-After` responses. Clients should still throttle responsibly. Avoid rapid duplicate requests, especially for broad list queries, large datasets, and document file downloads. Use pagination and targeted filters when available. For high-volume initial imports, broad firm-wide syncs, or frequent document downloads, coordinate expected request volume with Prevail support or the firm before live use. For retryable `503 Service Unavailable` or `504 Timeout` responses, retry with exponential backoff. For write retries, also follow the idempotency guidance above so a retry does not create duplicate Prevail data. ## Response Format Most successful responses are returned as JSON. Document file download endpoints return the raw file body instead. The exact response body depends on the endpoint and is documented in each endpoint example. The API returns the validated Prevail payload for that endpoint; it does not apply one global wrapper shape to every resource. ### Response Shape Guide | Response Type | Typical Shape | Notes | |---|---|---| | Matter and prospect lists | Top-level collection plus optional `pagination` | Collection keys are resource-specific, such as `matters` or `prospects`. | | Most other lists | Top-level collection plus optional `pagination` | Collection keys are resource-specific, such as `contacts`, `documents`, or `payments`. | | Single records | Top-level resource object | Keys are resource-specific, such as `matter`, `prospect`, `contact`, `document`, `task`, or `appointment`. | | Create and update responses | Created or updated resource data | Matter and prospect writes return top-level `matterid`; most other writes return the resource object. | | Document downloads | Binary file body | Successful downloads do not use JSON. Error responses return JSON. | ### Response Keys by Resource | Resource | List Key | Detail Key | Write or Action Key | Notes | |---|---|---|---|---| | Matters | `matters` | `matter` | `matterid` | Matter writes return the created or updated Prevail matter ID. | | Prospects | `prospects` | `prospect` | `matterid` | Prospect writes return the created or updated Prevail prospect/matter ID. | | Contacts | `contacts` | `contact` | `contact`, `communication`, `communications`, `address`, `addresses`, `matter_contact` | Communication, address, and matter-contact endpoints use their own keys. | | Documents | `documents` | `document` | `document` | Document file downloads return a binary file body instead of JSON. | | Ledger | `ledger_entries` | `ledger_entry` | `ledger_entry` | Standard list/detail/write resource payloads. | | Payments | `payments` | `payment` | `payment` | Standard list/detail/write resource payloads. | | Trust Payments | `trust_payments` | `trust_payment` | `trust_payment` | Standard list/detail/write resource payloads. | | Trust Deposits | `trust_deposits` | `trust_deposit` | `trust_deposit` | Standard list/detail/write resource payloads. | | Medical | `medical_records` | `medical_record` | `medical_record` | Metadata only. | | History | `history_records` | `history_record` | `history_record` | Metadata only. | | Employment | `employment_records` | `employment_record` | Not applicable | Read-only in V1. | | Disability | `disability_records` | `disability_record` | Not applicable | Read-only in V1. | | Process | `process_records` | `process_record` | Not applicable | Read-only in V1; also referred to as claims process records. | | SMS Messages | `sms_messages` | `sms_message` | Not applicable | Read-only in V1. | | Damages | `damage_records` | `damage_record` | `damage_record` | Metadata only. | | Liens | `lien_records` | `lien_record` | `lien_record` | Metadata only. | | Negotiations | `negotiation_records` | `negotiation_record` | `negotiation_record` | Metadata only. | | Evidence | `evidence_records` | `evidence_record` | `evidence_record` | Metadata only. | | Tasks | `tasks` | `task` | `task` | Complete and reopen actions return task data. | | Appointments | `appointments` | `appointment` | `appointment` | Create, update, cancel, and reschedule return appointment data. | | Lookups | Lookup-specific collection keys | Not applicable | Not applicable | See each lookup endpoint example. | ### List Responses Matter and prospect list endpoints return their resource payload directly as a top-level collection plus optional pagination: ```json { "matters": [ { "matterid": "12W34qop12", "title": "Example Matter" } ], "pagination": { "page": 1, "limit": 50, "has_more": false } } ``` Other list endpoints also return their resource payload directly, usually as a top-level collection plus optional pagination. See [Response Keys by Resource](#response-keys-by-resource) for collection names. ```json { "contacts": [ { "contact_id": "123", "display_name": "John Smith", "first_name": "John", "middle_name": null, "last_name": "Smith", "type": "Medical Provider" } ], "pagination": { "page": 1, "limit": 50, "has_more": false } } ``` When `include=contacts` is sent to a matter list or matter detail endpoint, related contacts may be included on each returned matter. When `include=documents` is sent to a matter detail endpoint, related documents may be included on the returned matter: ```json { "matter": { "matterid": "12W34qop12", "title": "Example Matter", "contacts": [ { "contact_id": "123", "display_name": "John Smith", "type": "Medical Provider", "role": "Treating Provider" } ], "documents": [ { "document_id": "history:abc123", "filename": "provider-summary.pdf", "type": "Document", "category": "Medical Records", "subject": "Medical Records", "date": "2026-04-22", "time": "14:30:00", "author": "KIM" } ] } } ``` ### Single Record Responses Matter and prospect detail endpoints return top-level resource objects, such as `matter` or `prospect`: ```json { "matter": { "matterid": "12W34qop12", "title": "Example Matter" } } ``` Other detail endpoints also return top-level resource objects. See [Response Keys by Resource](#response-keys-by-resource) for the detail key used by each resource. ```json { "contact": { "contact_id": "123", "display_name": "John Smith", "first_name": "John", "middle_name": null, "last_name": "Smith", "company_name": null, "type": "Medical Provider", "category": "Doctor", "primary_phone": "407-555-1234", "primary_email": "john@example.com", "address": { "address_type": "physical", "address_1": "123 Main St", "address_2": null, "city": "Orlando", "state": "FL", "zip": "32801" } } } ``` ### Create and Update Responses Matter and prospect create and update endpoints return the created or updated record ID as a top-level field: ```json { "matterid": "12W34qop12" } ``` Other create and update endpoints return top-level resource objects, such as `contact`, `document`, `payment`, `trust_payment`, `trust_deposit`, `medical_record`, `history_record`, `damage_record`, `lien_record`, `evidence_record`, `task`, `appointment`, `communication`, `address`, or `matter_contact`. Use [Response Keys by Resource](#response-keys-by-resource) for the list, detail, and write keys used by each resource. The appointment list response returns appointment records with fields such as `appointment_id`, `matterid`, `assigned_to`, `type`, `subject`, `status`, `date`, `end_date`, `start_time`, `end_time`, `notes`, `reminder_at`, `location`, `created`, `author`, `modified`, and `editor`. Single appointment, create, update, cancel, and reschedule responses return one appointment record. Treat `appointment_id` as an opaque value returned by appointment list, detail, create, update, cancel, or reschedule responses. ### Success Status Codes | Status | Meaning | |---|---| | `200 OK` | The request succeeded and returned data. | | `201 Created` | A new record was created. | ## Error Responses Errors are returned as JSON. Application error bodies include an `error_message` field. Portal validation errors include a top-level `message` and an `errors` object keyed by field name. Validation or configuration errors returned by the connected Prevail desktop include `error_message`, a stable `error_code`, and may also include field-level `errors` and a `request_id` for troubleshooting. Availability errors use the exact runtime messages shown in the endpoint response examples. The API does not add a request ID header or body field to every error response. Request IDs are used for processing and log correlation. If a response includes a request ID, include it when contacting support; not every endpoint or error path is guaranteed to return one. ### Error Shape Guide | Status Family | Body Shape | Common Cause | |---|---|---| | `401` / `403` | `error_message` | Missing, invalid, or unauthorized API credentials. | | `404` | `error_message` | The endpoint or requested record was not found. | | `409` | `error_message`, `error_code`, optionally plus `errors` and `request_id` | A current Prevail configuration conflict prevents an unambiguous write or lookup. | | `422` | `message` plus `errors`, or `error_message`, `error_code`, `errors`, and optionally `request_id` | A field is missing, blank, too long, in the wrong format, or rejected by the current Prevail layout. | | `500` | `error_message`, optionally plus `error_code` and `request_id` | Runtime issue while the connected Prevail desktop processes the request. | | `501` | `error_message` and `error_code` | The connected Prevail desktop does not implement the requested capability. | | `503` / `504` | `error_message` | Connection or timeout issue. | ### Example: Availability Error ```json { "error_message": "Prevail desktop is not connected" } ``` ### Example: Validation Error ```json { "message": "The subject field must not be greater than 200 characters.", "errors": { "subject": [ "The subject field must not be greater than 200 characters." ] } } ``` Connected Prevail lookup validation errors use this response format: ```json { "error_message": "Invalid contact type.", "error_code": "validation_error", "errors": { "type": "Use a contact type returned by the contact-types lookup." }, "request_id": "7fbce46d-0000-0000-0000-000000000000" } ``` Common status codes: | Status | Error | Meaning | |---|---|---| | `401` | Unauthorized | The request is missing API credentials, or one of the credential values is wrong. | | `403` | Forbidden | The API credentials are valid, but they are not allowed to access a firm. | | `404` | Not Found | The record or endpoint does not exist for the firm and ID you used. | | `422` | Validation Error | The request reached the API, but one or more fields are missing or in the wrong format. | | `500` | Server Error | Prevail hit an unexpected problem while processing the request. | | `501` | Capability Unavailable | The connected Prevail system does not support the requested capability. | | `503` | Prevail Unavailable | The connected Prevail system is not available. | | `504` | Timeout | The connected Prevail system did not answer before the request time limit. | ## Timeouts If a request takes too long because the connected Prevail system does not respond in time, the API may return a `504 Timeout` response with a runtime `error_message` such as `Timeout: no response from Prevail desktop`. **Write retry rule:** Before retrying a timed-out `POST`, `PUT`, or `PATCH`, check whether the record was already created or updated. Retrying blindly can create duplicate data or overwrite newer changes. Retry guidance: | Situation | Recommended Action | |---|---| | `503 Prevail Unavailable` | Confirm the connected Prevail system is available, then retry later using exponential backoff. | | `504 Timeout` on a `GET` request | Retry using exponential backoff. | | `504 Timeout` on a write request | Check whether the record was created or updated before retrying. | Avoid sending duplicate rapid requests for the same large dataset. Where possible, filter requests to only the records your integration needs. ## Troubleshooting | Problem | What to Check | |---|---| | `401 Unauthorized` | Confirm both API credential headers are present and correct. | | `403 Forbidden` | Confirm the API credentials are allowed to access the firm. | | `404 Not Found` | Confirm the endpoint path and record ID. | | `422 Validation Error` | Confirm required fields and field formats. | | `503 Prevail Unavailable` | The connected Prevail system may not be available. | | `504 Timeout` | Retry carefully and avoid duplicate write requests. | ## Versioning The public Base URL includes the versioned path segment `/api/v1/prevail`; endpoint-relative examples in this overview start after that base path, such as `/matters`. Breaking changes will be released under a new version prefix. Existing `v1` integrations should continue using the `v1` path until they are ready to move to a newer version. ## Support For API questions, contact `api.support@prevail.net`. Include: - Firm name. - Endpoint path. - Timestamp and time zone. - HTTP method. - HTTP status code. - Response body with sensitive values redacted. - Request ID, if returned. Do not include API credentials, Social Security numbers, full client data, document contents, medical details, or other sensitive data unless Prevail support specifically requests it through an approved secure channel. ## Get started with the Prevail API ### What you need The Prevail API is for approved server-to-server integrations. Before sending a request, obtain a firm-scoped **Client ID** and **Client Secret** from an authorized firm user. Outside developers cannot self-register credentials from these docs. Use this environment's Base URL for every request: ```http https://portal.prevail.net/api/v1/prevail ``` The generated [API Reference](/docs/api/prevail) is the source of truth for endpoint paths, parameters, request bodies, and response fields. ### Make your first request Start with a small, read-only request. It verifies the credentials and the connected Prevail system before an integration sends writes. ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/matters?openclosed=open" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` Matter list responses use a top-level `matters` collection. Use the returned `matterid` when retrieving matter-scoped records such as documents, tasks, payments, and history. ### Choose the next workflow | If you need to... | Start with | |---|---| | Find an existing matter | `GET /matters?openclosed=open` | | Find a person, company, or provider | `GET /contacts?search=` | | Read document metadata | `GET /documents?matter_id=` | | Use firm-defined categories or subjects | `GET /lookups/...` | | Create or update a record | A resource-specific write endpoint in the API reference | ### Keep the reference close Use **Getting Started** pages for the shared integration rules and **Tutorials** for end-to-end workflows. Use the generated reference whenever you need exact fields, constraints, sample payloads, or endpoint-specific response shapes. ## Authentication and secure access ### Send the required headers Every request must include both API credential headers issued by the law firm. JSON metadata requests should also send `Accept: application/json`. ```http X-Client-ID: X-Client-Secret: Accept: application/json ``` Use `Content-Type: application/json` for JSON `POST`, `PUT`, and `PATCH` bodies. Document upload endpoints use `multipart/form-data` instead. ### Treat credentials as secrets Client IDs and Client Secrets are firm-specific API key records. A valid pair authorizes access only to the firm that issued it. - Store the Client Secret on your server, never in browser JavaScript or a mobile app. - Never put credentials in a query string, source repository, public log, or support ticket. - Redact credentials and sensitive client data before sharing diagnostic information. - If a credential is exposed, ask the firm or Prevail support to revoke or replace it. ### Understand authorization failures | Status | Meaning | Next step | |---|---|---| | `401` | A credential header is missing or invalid. | Check both header names and values. | | `403` | The credential is valid but cannot access the firm. | Confirm the API key is assigned to the correct firm. | | `503` | The connected Prevail system is unavailable. | Retry later with backoff. | The full authentication, security, and sensitive-data guidance remains available in the [API Reference overview](/docs/api/prevail#/#authentication). ## Using Postman Import the Prevail API collection to test documented endpoints without building requests manually. Download Postman Collection ### Import the collection 1. Download `prevail-api.postman_collection.json`. 2. In Postman, select **Import** and choose the downloaded file. 3. Create or select a Postman environment and set `client_id` and `client_secret`. ### Configure the variables | Variable | Value | |---|---| | `base_url` | `http://prevail-master-portal.test/api/v1/prevail` | | `client_id` | Client ID issued by the law firm | | `client_secret` | Client Secret issued by the law firm | Store credential values as sensitive. Do not commit or share them. ### Test the connection Send the read-only **Matter → List matters** request: ```http GET {{base_url}}/matters?per_page=10 ``` Requests already include these headers: ```http Accept: application/json X-Client-ID: {{client_id}} X-Client-Secret: {{client_secret}} ``` Optional parameters are disabled by default. Replace path placeholders and review starter request bodies before sending. ## Read and synchronize Prevail data ### Filter before you fetch Use the endpoint-specific filters documented in the API Reference. Matter-scoped resources generally accept `matter_id` on firm-level list endpoints, while path values and responses may use Prevail's `matterid` spelling. Do not assume a filter, sort order, or pagination behavior applies to every resource. The individual endpoint reference is authoritative. ### Page through collections safely When an endpoint supports it, request `page=1` with an explicit `limit`. Continue only while `pagination.has_more` is present and `true`. 1. Request the first supported page. 2. Process every item in the returned collection. 3. Increment `page` only when `pagination.has_more` is `true`. 4. Stop when it is `false`. 5. If pagination metadata is absent, do not infer another page from collection size alone. ### Build incremental sync jobs Some list endpoints support `updated_since=YYYY-MM-DD`. It is inclusive and date-only, so store the last successful sync date, query from that date again, then deduplicate records using a stable ID and `modified` when that field is available. Deleted records are not returned as tombstones in V1 unless an endpoint explicitly says otherwise. Polling is the supported public integration pattern; V1 does not expose public webhook subscriptions. ### Next step Continue with [Find a matter and its related records](/docs/api/prevail?section=tutorials#/#find-a-matter-and-its-related-records), then use the relevant collection endpoint in the [API Reference](/docs/api/prevail). ## Reliable writes and troubleshooting ### Protect write retries Use an `Idempotency-Key` header on documented `POST` and `PATCH` writes whenever a network failure or timeout could lead to a retry. Generate one key for one logical write, store it until the work is complete, and reuse it only with the same method, URL, query string, body, and uploaded file content. ```http Idempotency-Key: payment--20260702-001 ``` An exact successful retry returns the original response and `Idempotency-Replayed: true`. Reusing a key for a different request returns `409 Conflict`. ### Respond to common failures | Situation | Recommended action | |---|---| | `422 Unprocessable Entity` | Correct the documented field errors and submit a new valid request. | | `503 Prevail Unavailable` | Retry later with exponential backoff. | | `504 Timeout` on `GET` | Retry using exponential backoff. | | `504 Timeout` on a write | Retry the exact request with the same idempotency key; do not create a new logical write until the original result is understood. | The API does not apply one response wrapper to every endpoint. Build clients against each endpoint's documented response example and its resource-specific top-level key. ### Get support safely When contacting support, include the firm name, endpoint path, time and time zone, method, status code, and a redacted response body. Do not include credentials, Social Security numbers, full client data, documents, or medical details unless requested through an approved secure channel. ## Find a matter and its related records ### Outcome Retrieve an open matter, then use its stable Prevail matter ID to read related contacts and document metadata. ### 1. Find the matter ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/matters?openclosed=open" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` Read the returned `matterid` from the selected item. Treat it as an opaque value; do not attempt to derive its format. ### 2. Retrieve related contacts Use the matter endpoint's documented `include` option when appropriate, or search contacts separately using the reference's documented filters. Contact IDs are also reused by several related resources. ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/matters/?include=contacts" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ### 3. Retrieve document metadata ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/documents?matter_id=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` This returns document metadata. Use the Document endpoints in the [API Reference](/docs/api/prevail) for exact download and replacement routes. ### Next step Use [Work with documents](#/#work-with-documents) when the integration must transfer files, or the [API Reference](/docs/api/prevail) for resource-specific fields and responses. ## Create or update data safely ### Outcome Create or update data only after using the firm's valid lookup values and preparing a safe retry key. ### 1. Read lookup values first Many write endpoints expect configured values such as categories, subjects, types, locations, users, or statuses. Fetch the relevant lookup list first and send the value exactly as returned. ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/lookups/appointment-locations" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` ### 2. Generate an idempotency key Create one unique value for this logical write. Save it with the job so a network retry sends the same key and request. ```http Idempotency-Key: integration-appointment--001 ``` ### 3. Send the documented write request Use the resource's generated endpoint reference for the exact route and body fields. Include both credential headers, `Accept: application/json`, `Content-Type: application/json`, and the idempotency key when the endpoint supports it. ### 4. Handle the result Store the returned opaque record ID. If the exact request is replayed successfully, the response includes `Idempotency-Replayed: true`; treat it as the original success, not a second write. Some financial and negotiation endpoints also require a body `idempotency_key` for the connected Prevail system. That field is separate from the HTTP `Idempotency-Key` header. ## Work with documents ### Outcome Read document metadata before transferring files, then use the generated Document endpoints for the exact upload, download, or replacement operation. ### 1. List document metadata ```bash curl --request GET "https://portal.prevail.net/api/v1/prevail/documents?matter_id=" \ --header "Accept: application/json" \ --header "X-Client-ID: " \ --header "X-Client-Secret: " ``` The result uses a top-level `documents` collection. Save the returned document identifier exactly as supplied. ### 2. Upload or replace a file Document upload endpoints use `multipart/form-data`, not JSON. The generated API reference documents the available upload and replacement paths, metadata fields, and required file field. Never log document contents or include them in unapproved support channels. For retries after a failed upload, use the same idempotency key only when the method, request data, file metadata, and file content are identical. ### 3. Download only what you need Successful document downloads return binary content rather than the standard JSON response format. Treat an error response from a download endpoint as JSON and inspect its status and `error_message` before retrying. ### Next step Open the [Document API Reference](/docs/api/prevail) and use its operation-specific request examples before implementing a live file transfer.