Organizations

18 endpoints in this category.

GET/organizations

Search Organizations

Search for organizations by name. Returns matching organizations with type and member count.

Authentication:Required — Authorization: Bearer <token>

Query Parameters

Name	Type	Required	Description
`search`	`string`	No	Search query

Response Fields

Name	Type	Required	Description
`data`	`Organization[]`	Yes	Array of matching organizations

Error Codes

Status	Meaning
`401`	Unauthorized

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET/my-organization

Get My Organization

Get details of the authenticated user's current organization.

Authentication:Required — Authorization: Bearer <token>

Response Fields

Name	Type	Required	Description
`data`	`Organization`	Yes	Organization details

Error Codes

Status	Meaning
`404`	User is not in an organization

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/organizations/:uuid/join-request

Request to Join Organization

Submit a request to join an organization. The org admin must approve.

Authentication:Required — Authorization: Bearer <token>

Path Parameters

Name	Type	Required	Description
`uuid`	`string`	Yes	Organization UUID

Error Codes

Status	Meaning
`404`	Organization not found
`409`	Already a member or pending request exists

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations/:uuid/join-request' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/my-organization/leave

Leave Organization

Leave the current organization. Subscription status may change from org_managed to expired.

Authentication:Required — Authorization: Bearer <token>

Error Codes

Status	Meaning
`404`	Not in an organization

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/leave' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/organizations/request

Request New Organization

Request that a new organization be added to the platform.

Authentication:Required — Authorization: Bearer <token>

Request Body

Name	Type	Required	Description
`name`	`string`	Yes	Organization name
`type`	`string`	Yes	Organization type (staffing_company, home_health_agency, clinic, private_practice, hospital)
`email`	`string`	No	Contact email for the org

Error Codes

Status	Meaning
`422`	Invalid organization type

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations/request' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "your_name",
  "type": "your_type",
  "email": "your_email"
}'

GET/my-join-requests

Get My Join Requests

List all pending join requests for the authenticated user.

Authentication:Required — Authorization: Bearer <token>

Response Fields

Name	Type	Required	Description
`data`	`JoinRequest[]`	Yes	Array of join requests

Error Codes

Status	Meaning
`401`	Unauthorized

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-join-requests' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET/my-organization/config

Get Effective App Configuration

The server-side answer to "what should this clinician's app show?". Returns the effective feature flags and terminology for the caller: solo clinicians get solo defaults overlaid with their personal overrides; organization members get their org's type defaults overlaid with the org's stored overrides (personal overrides are ignored the moment a clinician takes a seat). Feature flags: billing_codes, icd10_suggestions, staffing_offers, earnings, coverage_areas, follow_ups, ai_conversation, ai_voice, copy_last_visit, credential_sync, coverage_sync.

Authentication:Required — Authorization: Bearer <token>

Solo defaults are billing-off: billing_codes and icd10_suggestions default to false until the clinician opts in (most independents document, they don't code). Organization type defaults: staffing_company turns on staffing_offers, earnings, coverage_areas, follow_ups, credential_sync, coverage_sync; home_health_agency turns on follow_ups; clinic, private_practice, and hospital match solo defaults. credential_sync / coverage_sync are additionally forced false unless the server is actually wired to that org's back office, so the app never renders a sync affordance that would silently no-op. Render from THIS endpoint's answer — not from client-side org checks.

Response Fields

Name	Type	Required	Description
`source`	`string`	Yes	"solo" (defaults + personal overrides) or "organization" (org decides)
`features`	`object`	Yes	All 11 boolean feature flags, fully resolved
`terminology`	`object`	Yes	Display terminology — defaults: patient, visit, note ("visit note"), organization

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/config' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

PUT/my-organization/config

Update Organization Configuration

Organization admins customize what their clinicians' apps show: override any feature flag or terminology entry. Overrides layer on top of the org type's defaults. Feature flags: billing_codes, icd10_suggestions, staffing_offers, earnings, coverage_areas, follow_ups, ai_conversation, ai_voice, copy_last_visit, credential_sync, coverage_sync.

Authentication:Required — Authorization: Bearer <token>

Requires an admin seat. A null feature value clears the stored override entirely (deep-merge delete).

Request Body

Name	Type	Required	Description
`features`	`object`	No	Map of feature key → boolean, or null to clear a stored override (falls back to the org type default)
`terminology`	`object`	No	Map of term key → display string (e.g. call patients "clients")

Response Fields

Name	Type	Required	Description
`features`	`object`	Yes	The recomputed effective feature flags
`terminology`	`object`	Yes	The recomputed effective terminology

Error Codes

Status	Meaning
`403`	Caller is not an organization admin
`422`	Unknown feature keys (listed in the message) or non-boolean values

Code Examples

curl -X PUT 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/config' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "features": "{ \"billing_codes\": false }",
  "terminology": "{ \"patient\": \"client\" }"
}'

PUT/my-organization

Update Organization Profile

Organization admins update the org's own profile — name, contact details, and type.

Authentication:Required — Authorization: Bearer <token>

Changing type changes the org's default feature flags (stored overrides still win). The response includes the recomputed effective features so admin consoles can show exactly what changed.

Request Body

Name	Type	Required	Description
`name`	`string`	No	Organization display name
`email`	`string`	No	Contact email
`phone`	`string`	No	Contact phone
`address`	`string`	No	Mailing address
`type`	`string`	No	One of: staffing_company, home_health_agency, clinic, private_practice, hospital

Error Codes

Status	Meaning
`403`	Caller is not an organization admin
`422`	Invalid organization type

Code Examples

curl -X PUT 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "your_name",
  "email": "your_email",
  "phone": "your_phone",
  "address": "your_address",
  "type": "home_health_agency"
}'

POST/my-organization/invitations

Invite a Clinician

Organization admins invite a clinician by email. If the email has no VisitNote account, the invitee receives a deep link to create one; if they already have a solo account, the invitation appears in their app under Organization.

Authentication:Required — Authorization: Bearer <token>

One open invitation per (organization, email).

Request Body

Name	Type	Required	Description
`email`	`string`	Yes	Invitee email address
`role`	`string`	No	'member' (default) or 'admin'
`first_name`	`string`	No	Invitee first name (used in the email)
`last_name`	`string`	No	Invitee last name

Error Codes

Status	Meaning
`403`	Caller is not an organization admin
`422`	Email already belongs to a member of another organization, or an open invite already exists

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/invitations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "pt@example.com",
  "role": "member",
  "first_name": "your_first_name",
  "last_name": "your_last_name"
}'

GET/my-organization/invitations

List Sent Invitations

Organization admins list every invitation the org has sent, with status.

Authentication:Required — Authorization: Bearer <token>

Error Codes

Status	Meaning
`403`	Caller is not an organization admin

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/invitations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

DELETE/my-organization/invitations/:uuid

Revoke an Invitation

Organization admins revoke a pending invitation.

Authentication:Required — Authorization: Bearer <token>

Path Parameters

Name	Type	Required	Description
`uuid`	`string`	Yes	Invitation UUID

Error Codes

Status	Meaning
`403`	Caller is not an organization admin
`404`	Invitation not found

Code Examples

curl -X DELETE 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-organization/invitations/:uuid' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

GET/my-invitations

My Pending Invitations

Pending organization invitations addressed to the authenticated user's email.

Authentication:Required — Authorization: Bearer <token>

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-invitations' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/my-invitations/:uuid/accept

Accept an Invitation

Accept a pending organization invitation. Seats the user as a member of the organization in a single transaction (same writes as a join-request approval).

Authentication:Required — Authorization: Bearer <token>

Path Parameters

Name	Type	Required	Description
`uuid`	`string`	Yes	Invitation UUID

Error Codes

Status	Meaning
`404`	Invitation not found or not addressed to this user
`422`	User already belongs to an organization

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-invitations/:uuid/accept' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/my-invitations/:uuid/decline

Decline an Invitation

Decline a pending organization invitation.

Authentication:Required — Authorization: Bearer <token>

Path Parameters

Name	Type	Required	Description
`uuid`	`string`	Yes	Invitation UUID

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/my-invitations/:uuid/decline' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

POST/organizations/invite

Invite Your Organization

A clinician invites their organization to VisitNote. Creates a private (unlisted) organization record and emails the contact a claim link — when the org contact claims it, they become the org admin and the inviting clinician is seated automatically.

Authentication:Required — Authorization: Bearer <token>

Duplicate invites are deduplicated by organization name + contact email against open claims.

Request Body

Name	Type	Required	Description
`organization_name`	`string`	Yes	Organization name
`organization_type`	`string`	No	One of: staffing_company, home_health_agency, clinic, private_practice, hospital
`contact_name`	`string`	No	Name of the org contact to email
`contact_email`	`string`	Yes	Org contact email — receives the claim link
`message`	`string`	No	Optional personal note included in the email

Error Codes

Status	Meaning
`422`	An open claim already exists for this organization/contact

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations/invite' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "organization_name": "Sunrise Home Health",
  "organization_type": "your_organization_type",
  "contact_name": "your_contact_name",
  "contact_email": "admin@sunrisehh.com",
  "message": "your_message"
}'

GET/organizations/claim/:token

Preview an Organization Claim

Public, unauthenticated preview of a claim link — who invited which organization, and whether the token has expired. Contains no PHI.

Authentication:Not required

Path Parameters

Name	Type	Required	Description
`token`	`string`	Yes	Claim token from the invitation email

Response Fields

Name	Type	Required	Description
`organization_name`	`string`	Yes	The organization being claimed
`inviter_first_name`	`string`	Yes	First name of the inviting clinician
`expired`	`boolean`	Yes	Whether the token is no longer valid

Code Examples

curl -X GET 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations/claim/:token' \
  -H 'Accept: application/json'

POST/organizations/claim

Claim an Organization

The invited org contact — after registering or logging in — claims the organization. In one transaction: the org is approved and listed, the claimer is seated as admin, and the inviting clinician is seated as a member (if still org-less). Both parties are emailed.

Authentication:Required — Authorization: Bearer <token>

Request Body

Name	Type	Required	Description
`token`	`string`	Yes	Claim token from the invitation email

Error Codes

Status	Meaning
`404`	Unknown or already-consumed token
`422`	Token expired, or claimer already belongs to an organization

Code Examples

curl -X POST 'https://visitnote-api-production.up.railway.app/api/therapist/v1/organizations/claim' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "your_token"
}'