---
title: "Decide Referral"
method: POST
path: "/referrals/{referral_id}/decide"
tags: ["Referrals"]
---

# Decide Referral

`POST /referrals/{referral_id}/decide`

## Request

- Base URL: `https://api.openintake.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openintake.ai/referrals/{referral_id}/decide`
- Auth: none declared

Staff decide what a referral held for them does, then it runs again (or is closed).

use_contact: the client is this contact on their phone. new_contact: the
client is none of them. not_a_duplicate: a new case after all.
add_to_case: it belongs on the possible duplicate, so it's added to that
case instead (nothing on the case is overwritten). retry: run it again as
it is. close: end it without sending anything. Every decision is kept.

## Path parameters

- `referral_id` string, uuid, required

## Request body

- ReferralDecideRequest: What staff decided about a referral held for them.
  - `action` 'use_contact' | 'new_contact' | 'not_a_duplicate' | 'add_to_case' | 'retry' | 'close', required
  - `sa_contact_id` integer, nullable: use_contact: one of the held referral's contact candidates
  - `case_number` string, nullable: add_to_case: one of its possible duplicates
  - `note` string, nullable

## Response `200`

Successful Response

- ReferralResponse
  - `referral_id` string, uuid, required
  - `first_name` string, required
  - `last_name` string, required
  - `email` string, nullable
  - `phone_number` string, nullable
  - `preferred_language` string, required
  - `preferred_language_other` string, nullable
  - `case_description` string, nullable
  - `address_line1` string, nullable
  - `address_line2` string, nullable
  - `city` string, nullable
  - `state` string, nullable
  - `zip_code` string, nullable
  - `county` string, nullable
  - `date_of_birth` string, date, nullable
  - `ssn_last4` string, nullable: Last four digits only; the full SSN is never returned
  - `incident_date` string, date, nullable
  - `intake` ReferralIntakeOutput
    - `referral` ReferralHowReferred: How the client came to the firm, when the partner isn't the source.
      - `channel` 'prior_client' | 'friend_or_family' | 'law_firm' | 'advertising' | 'other', nullable
      - `name` string, nullable: Who: the firm, the ad, or the person
    - `incident` ReferralIncident
      - `incident_type` 'car_accident' | 'premises' | 'other', nullable
      - `incident_type_other` string, nullable
      - `time` string, nullable: Time of day, e.g. 3:15 PM
      - `location` string, nullable
      - `street` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `county` string, nullable
      - `description` string, nullable
      - `client_role` 'driver' | 'passenger' | 'pedestrian' | 'bicyclist' | 'other', nullable
      - `police_responded` boolean, nullable
      - `police_report_filed` boolean, nullable
      - `police_department` string, nullable: Agency / precinct
      - `police_report_number` string, nullable
      - `tickets_or_arrests` boolean, nullable
      - `tickets_or_arrests_details` string, nullable
      - `property_damage` boolean, nullable
      - `property_damage_description` string, nullable
    - `treatment` ReferralTreatment
      - `injuries` string, nullable: Describe the injuries
      - `ambulance_on_scene` boolean, nullable
      - `transported_by_ambulance` boolean, nullable
      - `hospital_name` string, nullable
      - `hospital_visit` 'emergency' | 'outpatient' | 'inpatient', nullable
      - `admission_date` string, date, nullable
      - `treated_by_doctor` boolean, nullable
      - `medical_providers` ReferralMedicalProvider[]
        - `name` string, nullable
        - `address` string, nullable
      - `treatment_ongoing` boolean, nullable
    - `client_vehicle` ReferralVehicle
      - `owner_name` string, nullable
      - `driver_name` string, nullable
      - `year` string, nullable
      - `make` string, nullable
      - `model` string, nullable
      - `color` string, nullable
      - `plate_number` string, nullable
      - `plate_state` string, nullable
      - `insurance_company` string, nullable
      - `policy_number` string, nullable
      - `claim_number` string, nullable
    - `other_vehicle` ReferralVehicle
      - `owner_name` string, nullable
      - `driver_name` string, nullable
      - `year` string, nullable
      - `make` string, nullable
      - `model` string, nullable
      - `color` string, nullable
      - `plate_number` string, nullable
      - `plate_state` string, nullable
      - `insurance_company` string, nullable
      - `policy_number` string, nullable
      - `claim_number` string, nullable
    - `health_insurance` ReferralHealthInsurance
      - `has_health_insurance` boolean, nullable
      - `types` string[]
      - `company` string, nullable
      - `medicare_id` string, nullable
    - `household` ReferralHousehold
      - `lives_alone` boolean, nullable
      - `members` ReferralPerson[]
        - `name` string, nullable
        - `relationship` string, nullable
        - `phone` string, nullable
        - `address` string, nullable
        - `date_of_birth` string, date, nullable
      - `household_vehicle` boolean, nullable: Does the client or a relative they live with own a vehicle?
      - `household_vehicle_details` string, nullable: Owner, insurance company, policy number
    - `employment` ReferralEmployment
      - `employed` boolean, nullable
      - `employer_name` string, nullable
      - `employer_address` string, nullable
      - `occupation` string, nullable
      - `weekly_earnings` string, nullable
      - `hours_per_day` string, nullable
      - `on_job_injury` boolean, nullable
      - `lost_time_from_work` boolean, nullable
      - `lost_time_details` string, nullable
      - `receiving_unemployment` boolean, nullable
      - `disability_or_workers_comp` boolean, nullable
    - `witnesses` ReferralPerson[]
      - `name` string, nullable
      - `relationship` string, nullable
      - `phone` string, nullable
      - `address` string, nullable
      - `date_of_birth` string, date, nullable
    - `prior_attorney` ReferralPriorAttorney
      - `has_prior_attorney` boolean, nullable
      - `firm_name` string, nullable
      - `attorney_name` string, nullable
      - `address` string, nullable
      - `phone` string, nullable
    - `prior_injuries_or_claims` boolean, nullable
    - `prior_claims_details` string, nullable
    - `other_expenses` string, nullable
    - `additional_notes` string, nullable
    - `additional_plaintiffs` ReferralAdditionalPlaintiffOutput[]
      - `first_name` string, required
      - `last_name` string, required
      - `relationship` string, nullable: To the main client, e.g. wife, son
      - `phone` string, nullable
      - `email` string, nullable
      - `same_address` boolean: Lives at the main client's address
      - `address_line1` string, nullable
      - `address_line2` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `zip_code` string, nullable
      - `date_of_birth` string, date, nullable
      - `preferred_language` 'en' | 'es' | 'other', nullable
      - `preferred_language_other` string, nullable
      - `role` 'driver' | 'passenger' | 'pedestrian' | 'bicyclist' | 'other', nullable
      - `treatment` ReferralTreatment
        - `injuries` string, nullable: Describe the injuries
        - `ambulance_on_scene` boolean, nullable
        - `transported_by_ambulance` boolean, nullable
        - `hospital_name` string, nullable
        - `hospital_visit` 'emergency' | 'outpatient' | 'inpatient', nullable
        - `admission_date` string, date, nullable
        - `treated_by_doctor` boolean, nullable
        - `medical_providers` ReferralMedicalProvider[]
          - `name` string, nullable
          - `address` string, nullable
        - `treatment_ongoing` boolean, nullable
      - `health_insurance` ReferralHealthInsurance
        - `has_health_insurance` boolean, nullable
        - `types` string[]
        - `company` string, nullable
        - `medicare_id` string, nullable
      - `employment` ReferralEmployment
        - `employed` boolean, nullable
        - `employer_name` string, nullable
        - `employer_address` string, nullable
        - `occupation` string, nullable
        - `weekly_earnings` string, nullable
        - `hours_per_day` string, nullable
        - `on_job_injury` boolean, nullable
        - `lost_time_from_work` boolean, nullable
        - `lost_time_details` string, nullable
        - `receiving_unemployment` boolean, nullable
        - `disability_or_workers_comp` boolean, nullable
  - `push_result` ReferralPushResult: What the last push did — or, on a dry run, would do.
    - `plan_only` boolean, required
    - `steps` ReferralPushStep[]
      - `key` string, required
      - `label` string, required
      - `status` string, required
      - `detail` string, nullable
      - `sa_id` integer, nullable
      - `written` object[]
    - `payloads` object
    - `blocked` string, nullable: Why a dry-run plan could not be built
    - `possible_duplicates` ReferralPossibleDuplicate[]
      - `case_number` string, required
      - `sa_contact_id` integer, required
      - `matched_on` string, required: How the client matched the case's contact: "phone", "email" or "name and date of birth"
      - `incident_date` string, date, nullable: The case's date of incident
      - `case_status` string, nullable
    - `different_incident` boolean
    - `contact_candidates` ReferralContactCandidate[]
      - `sa_contact_id` integer, required
      - `name` string
      - `date_of_birth` string, nullable
      - `email` string, nullable
      - `case_roles` object: Cases they're on, by role ("Plaintiff", "Intake Paralegal"…)
      - `firm_side` boolean: On cases only in firm roles, never as a plaintiff
    - `plaintiffs` object[]
  - `attachments` ReferralAttachmentDetail[]
    - `referral_attachment_id` string, uuid, required
    - `doc_type` string, required
    - `file_name` string, required
    - `content_type` string, nullable
    - `size_bytes` integer, required
    - `sa_document_id` integer, nullable
    - `download_url` string, nullable
    - `read_status` string, nullable
    - `detected_doc_type` string, nullable
    - `summary` string, nullable
  - `status` string, required
  - `needs_attention_reason` string, nullable
  - `sa_contact_id` integer, nullable
  - `sa_case_id` integer, nullable
  - `sa_case_number` string, nullable
  - `matched_existing_contact` boolean, required
  - `was_dry_run` boolean, required
  - `assuresign_status` string, required
  - `partner_name` string, required
  - `partner_firm_name` string, nullable
  - `source` 'referral_portal' | 'intake_link'
  - `submitted_at` string, date-time, required
  - `processed_at` string, date-time, nullable
  - `continues_case_number` string, nullable
  - `decisions` ReferralDecision[]
    - `action` string, required
    - `detail` string, nullable
    - `by` string, required
    - `at` string, date-time, required
  - `sends_to_smartadvocate` boolean, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-26** `62d10ad76f8c`: 4 info
  - added the optional property `push_result/anyOf[subschema #1: ReferralPushResult]/different_incident` to the response with the `200` status
  - added the optional property `push_result/anyOf[subschema #1: ReferralPushResult]/possible_duplicates/items/case_status` to the response with the `200` status
  - added the optional property `push_result/anyOf[subschema #1: ReferralPushResult]/possible_duplicates/items/incident_date` to the response with the `200` status
  - added the optional property `source` to the response with the `200` status
- **2026-10-21** `1e3d95fc77b0`: 1 info
  - added the optional property `intake/anyOf[subschema #1: ReferralIntake]/incident/location` to the response with the `200` status
- **2026-10-21** `62b223e8ec22`: 1 info
  - added the optional property `sends_to_smartadvocate` to the response with the `200` status
- **2026-10-21** `2f23018e6e01`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openintake/apis/openintake-api/changes/referrals/:referral_id/decide/post.md)

---

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