Referrals

18 endpoints

Patient Attributions

4 endpoints

get/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions

List patient attributions

List referral attributions for a patient with pagination. Returns attribution records showing how this patient was acquired. Each record links to exactly one source: a marketing referral source, referral partner, in-house provider, or referring patient. Error conditions: - 404: Patient not found.

Parameters

Path Parameters

patient_uuidstringrequired

org_idstringrequired

Query Parameters

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of records per page.

Default: 50

Responses

200Successful Response

itemsobject[]required

List of referral attributions for the patient.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of records per page.

totalintegerrequired

Total number of attributions.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

post/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions

Create patient attribution

Record a referral attribution for a patient. Tracks how this patient was acquired. Exactly one source reference must be provided (referral_source_uuid, referral_partner_uuid, provider_uuid, or referring_patient_uuid). Only one active 'primary' attribution is allowed per patient. Error conditions: - 404: Patient or referenced source/partner/provider not found. - 409: Patient already has a primary attribution. - 422: No source provided, or multiple sources provided.

Parameters

Path Parameters

patient_uuidstringrequired

org_idstringrequired

Request Body

attribution_roleenum

Role of this attribution in the patient's acquisition. One of: primary (first-touch attribution set at intake), secondary (additional touchpoint), assist (contributing factor).

assistprimarysecondary

provider_uuidstring (uuid)

referral_partner_uuidstring (uuid)

referral_source_uuidstring (uuid)

referring_patient_uuidstring (uuid)

source_notestring

Responses

201Successful Response

attributed_atstring (date-time)required

Timestamp when the attribution was recorded.

attribution_roleenum

Role of this attribution in the patient's acquisition. One of: primary (first-touch attribution set at intake), secondary (additional touchpoint), assist (contributing factor).

assistprimarysecondary

created_atstring (date-time)required

Timestamp when the record was created.

idstring (uuid)required

Unique identifier of the attribution record.

patientobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

referral_partnerobject

Lightweight reference to a related entity — exposes UUID and optional name.

referral_sourceobject

Lightweight reference to a related entity — exposes UUID and optional name.

referring_patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

source_notestring

updated_atstring (date-time)required

Timestamp when the record was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attribution_role": "assist",
    "provider_uuid": "string",
    "referral_partner_uuid": "string",
    "referral_source_uuid": "string",
    "referring_patient_uuid": "string"
  }'

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attribution_role": "assist",
    "provider_uuid": "string",
    "referral_partner_uuid": "string",
    "referral_source_uuid": "string",
    "referring_patient_uuid": "string"
  }'

post/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}/archive

Archive patient attribution

Soft-delete a referral attribution. Verifies ownership before archiving. Error conditions: - 404: Patient or attribution not found, or attribution does not belong to this patient. - 409: Version conflict — the attribution was modified since last read.

Parameters

Path Parameters

patient_uuidstringrequired

attribution_uuidstringrequired

org_idstringrequired

Query Parameters

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

Responses

200Successful Response

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

patch/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}

Update patient attribution

Update a referral attribution. Only attribution_role and source_note can be modified. Source references (referral_source, referral_partner, provider, referring_patient) are immutable after creation. Requires base_version for optimistic concurrency control. Verifies that the attribution belongs to the specified patient. Error conditions: - 404: Patient or attribution not found, or attribution does not belong to this patient. - 409: Version conflict — the attribution was modified since last read.

Parameters

Path Parameters

patient_uuidstringrequired

attribution_uuidstringrequired

org_idstringrequired

Request Body

attribution_roleenum

assistprimarysecondary

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

source_notestring

Responses

200Successful Response

attributed_atstring (date-time)required

Timestamp when the attribution was recorded.

attribution_roleenum

Role of this attribution in the patient's acquisition. One of: primary (first-touch attribution set at intake), secondary (additional touchpoint), assist (contributing factor).

assistprimarysecondary

created_atstring (date-time)required

Timestamp when the record was created.

idstring (uuid)required

Unique identifier of the attribution record.

patientobjectrequired

Lightweight reference to a related entity — exposes UUID and optional name.

providerobject

Lightweight reference to a related entity — exposes UUID and optional name.

referral_partnerobject

Lightweight reference to a related entity — exposes UUID and optional name.

referral_sourceobject

Lightweight reference to a related entity — exposes UUID and optional name.

referring_patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

source_notestring

updated_atstring (date-time)required

Timestamp when the record was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attribution_role": "string",
    "base_version": 1,
    "source_note": "string"
  }'

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/patients/{patient_uuid}/referral-attributions/{attribution_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "attribution_role": "string",
    "base_version": 1,
    "source_note": "string"
  }'

Partners

5 endpoints

get/api/v1/{org_id}/referral-partners

List referral partners

List referral partners with pagination and filters. Returns a paginated list of referral partners. Supports filtering by contact type, specialty, and active status, plus free-text search across name, practice name, and NPI fields.

Parameters

Path Parameters

org_idstringrequired

Query Parameters

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of records per page.

Default: 50

contact_typestring

Filter by contact type

specialtystring

Filter by specialty

is_activeboolean

Filter by active status

searchstring

Search by name, practice, or NPI

Responses

200Successful Response

itemsobject[]required

List of referral partners matching the query.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of records per page.

totalintegerrequired

Total number of partners matching the query.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-partners" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-partners" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

get/api/v1/{org_id}/referral-partners/{referral_partner_uuid}

Get referral partner by ID

Retrieve a single referral partner by UUID. Error conditions: - 404: Referral partner not found.

Parameters

Path Parameters

referral_partner_uuidstringrequired

org_idstringrequired

Responses

200Successful Response

accepts_ereferralboolean

Whether this partner accepts electronic referrals. If true, ereferral_endpoint is required.

address_line1string

address_line2string

citystring

contact_typeenum

Type of referral contact. One of: provider (individual practitioner), practice (dental or medical office), lab (dental laboratory), other.

labotherpracticeprovider

countrystring

Country code. Defaults to 'US'.

created_atstring (date-time)required

Timestamp when the partner was created.

emailstring

ereferral_endpointstring

faxstring

first_namestring

idstring (uuid)required

Unique identifier of the referral partner.

is_activeboolean

Whether this partner is currently active and available for referrals.

last_namestring

notesstring

npistring

phonestring

postal_codestring

practice_namestring

preferred_contact_methodenum

emailfaxphoneportal

specialtystring

statestring

updated_atstring (date-time)required

Timestamp when the partner was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

post/api/v1/{org_id}/referral-partners

Create referral partner

Create a new referral partner. Registers an external provider, practice, lab, or other contact for referral tracking. Partners with contact_type 'provider' require first_name and last_name. If accepts_ereferral is true, ereferral_endpoint must be provided. Error conditions: - 422: Validation error (missing required name fields, invalid NPI format).

Parameters

Path Parameters

org_idstringrequired

Request Body

accepts_ereferralboolean

Whether this partner accepts electronic referrals. If true, ereferral_endpoint is required.

address_line1string

address_line2string

citystring

contact_typeenum

Type of referral contact. One of: provider (individual practitioner), practice (dental or medical office), lab (dental laboratory), other.

labotherpracticeprovider

countrystring

Country code. Defaults to 'US'.

emailstring

ereferral_endpointstring

faxstring

first_namestring

is_activeboolean

Whether this partner is currently active and available for referrals.

last_namestring

notesstring

npistring

phonestring

postal_codestring

practice_namestring

preferred_contact_methodenum

emailfaxphoneportal

specialtystring

statestring

Responses

201Successful Response

accepts_ereferralboolean

Whether this partner accepts electronic referrals. If true, ereferral_endpoint is required.

address_line1string

address_line2string

citystring

contact_typeenum

Type of referral contact. One of: provider (individual practitioner), practice (dental or medical office), lab (dental laboratory), other.

labotherpracticeprovider

countrystring

Country code. Defaults to 'US'.

created_atstring (date-time)required

Timestamp when the partner was created.

emailstring

ereferral_endpointstring

faxstring

first_namestring

idstring (uuid)required

Unique identifier of the referral partner.

is_activeboolean

Whether this partner is currently active and available for referrals.

last_namestring

notesstring

npistring

phonestring

postal_codestring

practice_namestring

preferred_contact_methodenum

emailfaxphoneportal

specialtystring

statestring

updated_atstring (date-time)required

Timestamp when the partner was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-partners" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accepts_ereferral": false,
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "contact_type": "lab"
  }'

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-partners" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accepts_ereferral": false,
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "contact_type": "lab"
  }'

post/api/v1/{org_id}/referral-partners/{referral_partner_uuid}/archive

Archive referral partner

Soft-delete a referral partner. Sets deleted_at timestamp. The partner is excluded from normal queries but data is preserved. Error conditions: - 404: Referral partner not found. - 409: Version conflict — the partner was modified since last read.

Parameters

Path Parameters

referral_partner_uuidstringrequired

org_idstringrequired

Query Parameters

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

Responses

200Successful Response

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

patch/api/v1/{org_id}/referral-partners/{referral_partner_uuid}

Update referral partner

Update a referral partner. Uses PATCH semantics — only provided fields are modified. Requires base_version for optimistic concurrency control. Error conditions: - 404: Referral partner not found. - 409: Version conflict — the partner was modified since last read. - 422: Validation error (provider without name, e-referral without endpoint).

Parameters

Path Parameters

referral_partner_uuidstringrequired

org_idstringrequired

Request Body

accepts_ereferralboolean

address_line1string

address_line2string

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

citystring

contact_typeenum

labotherpracticeprovider

countrystring

emailstring

ereferral_endpointstring

faxstring

first_namestring

is_activeboolean

last_namestring

notesstring

npistring

phonestring

postal_codestring

practice_namestring

preferred_contact_methodenum

emailfaxphoneportal

specialtystring

statestring

Responses

200Successful Response

accepts_ereferralboolean

Whether this partner accepts electronic referrals. If true, ereferral_endpoint is required.

address_line1string

address_line2string

citystring

contact_typeenum

Type of referral contact. One of: provider (individual practitioner), practice (dental or medical office), lab (dental laboratory), other.

labotherpracticeprovider

countrystring

Country code. Defaults to 'US'.

created_atstring (date-time)required

Timestamp when the partner was created.

emailstring

ereferral_endpointstring

faxstring

first_namestring

idstring (uuid)required

Unique identifier of the referral partner.

is_activeboolean

Whether this partner is currently active and available for referrals.

last_namestring

notesstring

npistring

phonestring

postal_codestring

practice_namestring

preferred_contact_methodenum

emailfaxphoneportal

specialtystring

statestring

updated_atstring (date-time)required

Timestamp when the partner was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accepts_ereferral": null,
    "address_line1": "string",
    "address_line2": "string",
    "base_version": 1,
    "city": "string"
  }'

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-partners/{referral_partner_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accepts_ereferral": null,
    "address_line1": "string",
    "address_line2": "string",
    "base_version": 1,
    "city": "string"
  }'

Sources

5 endpoints

get/api/v1/{org_id}/referral-sources

List referral sources

List referral sources with pagination and filters. Returns a paginated list of marketing attribution sources with computed statistics (patient_count, total_cost) for each source. Supports filtering by category and active status, plus name search.

Parameters

Path Parameters

org_idstringrequired

Query Parameters

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of records per page.

Default: 50

categorystring

Filter by category

is_activeboolean

Filter by active status

searchstring

Search by name

Responses

200Successful Response

itemsobject[]required

List of referral sources matching the query.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of records per page.

totalintegerrequired

Total number of sources matching the query.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

get/api/v1/{org_id}/referral-sources/{referral_source_uuid}

Get referral source by ID

Retrieve a single referral source by UUID. Returns the source with linked references and computed statistics (patient_count, total_cost). Error conditions: - 404: Referral source not found.

Parameters

Path Parameters

referral_source_uuidstringrequired

org_idstringrequired

Responses

200Successful Response

categorystringrequired

Marketing attribution category. One of: patient_referral, doctor_referral, digital_advertising, organic_search, social_media, online_directory, website, insurance_plan, direct_mail, print_media, community_event, signage, tv_radio, email_marketing, walk_in, internal_transfer, other.

created_atstring (date-time)required

Timestamp when the source was created.

descriptionstring

idstring (uuid)required

Unique identifier of the referral source.

is_activeboolean

Whether this source is currently active and available for attribution.

linked_patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

linked_referral_partnerobject

Lightweight reference to a related entity — exposes UUID and optional name.

namestringrequired

Display name of the referral source (e.g. 'Google Ads - Spring 2026', 'Dr. Smith (Periodontist)').

patient_countinteger

Computed: number of patients attributed to this source.

sort_orderintegerrequired

Display sort order for the source in lists.

total_costnumber

Computed: total marketing spend recorded for this source across all periods.

updated_atstring (date-time)required

Timestamp when the source was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

post/api/v1/{org_id}/referral-sources

Create referral source

Create a new referral source for marketing attribution. A referral source represents a marketing channel or person that brings patients to the practice (e.g. 'Google Ads', 'Patient Referral', 'Walk-in'). Sources with category 'patient_referral' should link to a patient; 'doctor_referral' should link to a referral partner. Returns the created source with computed patient_count and total_cost. Error conditions: - 404: Linked patient or referral partner not found. - 422: Invalid category value, or both patient and partner linked.

Parameters

Path Parameters

org_idstringrequired

Request Body

categorystringrequired

descriptionstring

is_activeboolean

Whether this source is currently active and available for attribution.

linked_patient_uuidstring (uuid)

linked_referral_partner_uuidstring (uuid)

namestringrequired

Display name of the referral source (e.g. 'Google Ads - Spring 2026', 'Dr. Smith (Periodontist)').

Responses

201Successful Response

categorystringrequired

created_atstring (date-time)required

Timestamp when the source was created.

descriptionstring

idstring (uuid)required

Unique identifier of the referral source.

is_activeboolean

Whether this source is currently active and available for attribution.

linked_patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

linked_referral_partnerobject

Lightweight reference to a related entity — exposes UUID and optional name.

namestringrequired

Display name of the referral source (e.g. 'Google Ads - Spring 2026', 'Dr. Smith (Periodontist)').

patient_countinteger

Computed: number of patients attributed to this source.

sort_orderintegerrequired

Display sort order for the source in lists.

total_costnumber

Computed: total marketing spend recorded for this source across all periods.

updated_atstring (date-time)required

Timestamp when the source was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "string",
    "description": "string",
    "is_active": true,
    "linked_patient_uuid": "string",
    "linked_referral_partner_uuid": "string",
    "name": "string"
  }'

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "string",
    "description": "string",
    "is_active": true,
    "linked_patient_uuid": "string",
    "linked_referral_partner_uuid": "string",
    "name": "string"
  }'

post/api/v1/{org_id}/referral-sources/{referral_source_uuid}/archive

Archive referral source

Soft-delete a referral source. Existing patient attributions referencing this source are preserved. Error conditions: - 404: Referral source not found. - 409: Version conflict — the source was modified since last read.

Parameters

Path Parameters

referral_source_uuidstringrequired

org_idstringrequired

Query Parameters

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

Responses

200Successful Response

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

patch/api/v1/{org_id}/referral-sources/{referral_source_uuid}

Update referral source

Update a referral source. Uses PATCH semantics — only provided fields are modified. Linked patient and partner references can be updated or cleared. Requires base_version for optimistic concurrency control. Error conditions: - 404: Referral source, linked patient, or linked partner not found. - 409: Version conflict — the source was modified since last read. - 422: Invalid category or mutually exclusive links violated.

Parameters

Path Parameters

referral_source_uuidstringrequired

org_idstringrequired

Request Body

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

categorystring

descriptionstring

is_activeboolean

linked_patient_uuidstring (uuid)

linked_referral_partner_uuidstring (uuid)

namestring

Responses

200Successful Response

categorystringrequired

created_atstring (date-time)required

Timestamp when the source was created.

descriptionstring

idstring (uuid)required

Unique identifier of the referral source.

is_activeboolean

Whether this source is currently active and available for attribution.

linked_patientobject

Lightweight reference to a related entity — exposes UUID and optional name.

linked_referral_partnerobject

Lightweight reference to a related entity — exposes UUID and optional name.

namestringrequired

Display name of the referral source (e.g. 'Google Ads - Spring 2026', 'Dr. Smith (Periodontist)').

patient_countinteger

Computed: number of patients attributed to this source.

sort_orderintegerrequired

Display sort order for the source in lists.

total_costnumber

Computed: total marketing spend recorded for this source across all periods.

updated_atstring (date-time)required

Timestamp when the source was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "description": "string",
    "is_active": null,
    "linked_patient_uuid": "string"
  }'

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_version": 1,
    "category": "string",
    "description": "string",
    "is_active": null,
    "linked_patient_uuid": "string"
  }'

Source Costs

4 endpoints

get/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs

List source costs

List cost records for a referral source with pagination. Returns campaign spend entries ordered by period. Used for marketing ROI calculation (Cost Per Acquisition = Total Spend / New Patients). Error conditions: - 404: Referral source not found.

Parameters

Path Parameters

referral_source_uuidstringrequired

org_idstringrequired

Query Parameters

pageinteger

Page number (1-based).

Default: 1

page_sizeinteger

Number of records per page.

Default: 50

Responses

200Successful Response

itemsobject[]required

List of cost records for the referral source.

pageintegerrequired

Current page number (1-based).

page_sizeintegerrequired

Number of records per page.

totalintegerrequired

Total number of cost records.

422Validation Error

detailobject[]

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X GET "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

post/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs

Record source cost

Record a marketing spend entry for a referral source. Tracks campaign costs by time period for ROI analysis. period_end must be >= period_start and amount must be >= 0. Error conditions: - 404: Referral source not found. - 422: period_end < period_start, or negative amount.

Parameters

Path Parameters

referral_source_uuidstringrequired

org_idstringrequired

Request Body

amountnumberrequired

notesstring

period_endstring (date)required

End date of the cost tracking period. Must be >= period_start.

period_startstring (date)required

Start date of the cost tracking period.

Responses

201Successful Response

amountstringrequired

Marketing spend amount in dollars for this period. Must be >= 0 with at most 2 decimal places.

created_atstring (date-time)required

Timestamp when the cost record was created.

idstring (uuid)required

Unique identifier of the cost record.

notesstring

period_endstring (date)required

End date of the cost tracking period. Must be >= period_start.

period_startstring (date)required

Start date of the cost tracking period.

updated_atstring (date-time)required

Timestamp when the cost record was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "notes": "string",
    "period_end": "2025-01-15",
    "period_start": "2025-01-15"
  }'

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "notes": "string",
    "period_end": "2025-01-15",
    "period_start": "2025-01-15"
  }'

post/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}/archive

Archive source cost

Soft-delete a cost record. Verifies ownership before archiving. Error conditions: - 404: Referral source or cost record not found, or cost does not belong to this source. - 409: Version conflict — the cost record was modified since last read.

Parameters

Path Parameters

referral_source_uuidstringrequired

cost_uuidstringrequired

org_idstringrequired

Query Parameters

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

Responses

200Successful Response

422Validation Error

detailobject[]

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

curl

curl -X POST "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

patch/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}

Update source cost

Update a cost record. Verifies that the cost record belongs to the specified referral source. Requires base_version for optimistic concurrency control. Error conditions: - 404: Referral source or cost record not found, or cost does not belong to this source. - 409: Version conflict — the cost record was modified since last read. - 422: Invalid amount or period dates.

Parameters

Path Parameters

referral_source_uuidstringrequired

cost_uuidstringrequired

org_idstringrequired

Request Body

amountnumber

base_versionintegerrequired

Current version for optimistic concurrency. Rejected with 409 if stale.

notesstring

period_endstring (date)

period_startstring (date)

Responses

200Successful Response

amountstringrequired

Marketing spend amount in dollars for this period. Must be >= 0 with at most 2 decimal places.

created_atstring (date-time)required

Timestamp when the cost record was created.

idstring (uuid)required

Unique identifier of the cost record.

notesstring

period_endstring (date)required

End date of the cost tracking period. Must be >= period_start.

period_startstring (date)required

Start date of the cost tracking period.

updated_atstring (date-time)required

Timestamp when the cost record was last updated.

versionintegerrequired

Optimistic concurrency version number.

422Validation Error

detailobject[]

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "base_version": 1,
    "notes": "string",
    "period_end": "string",
    "period_start": "string"
  }'

curl

curl -X PATCH "https://api.example.com/api/v1/{org_id}/referral-sources/{referral_source_uuid}/costs/{cost_uuid}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": null,
    "base_version": 1,
    "notes": "string",
    "period_end": "string",
    "period_start": "string"
  }'