logo
API docs by Redocly

Senior Place API (DRAFT)

Download OpenAPI specification:

Senior Place Support: engineering@seniorplace.com

DRAFT API SPECIFICATION - Subject to Change

This is a draft specification for the Senior Place API. The endpoints and schemas described here are not yet implemented and may change before the final release.

Overview

API for creating and managing client records in Senior Place CRM.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: ApiKey YOUR_API_KEY

API keys can be generated from your tenant's admin panel. Each API key can be given specific permissions or roles.

Client Management

Operations for managing client records

List available client statuses

Returns all available client statuses for your tenant. Use the returned status IDs when creating clients.

Note: Status IDs are unique per tenant. The same status name may have different IDs across tenants.

Authorizations:
ApiKeyAuth
query Parameters
includeArchived
boolean
Default: false

Include archived statuses in the response

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Create a new client

Creates a new client record in the CRM.

Required Fields

  • statusId: Must be a valid status ID from your tenant (only required field)

Custom Fields

Custom fields are tenant-specific. To include custom field answers:

  1. Provide the question's key (slug) and the answer value
  2. The value type depends on the question type (text, boolean, number, range)

Contacts

You can include multiple related contacts (family members, friends, POA, etc.) in the contacts array.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
statusId
required
string <uuid>

The ID of the client status. Must be a valid status ID for your tenant. Use the /client-statuses endpoint to get available status IDs.

name
string or null

Full name of the client (the senior)

preferredName
string

Preferred name or nickname

email
string <email>

Client's email address

phone
string

Client's phone number (will be normalized to E.164 format)

gender
string
Enum: "Female" "Male" "Other"

Client's gender

maritalStatus
string
Enum: "Single" "Married" "Divorced" "Widowed" "Separated" "Domestic Partnership"

Marital status

dateOfBirth
string <date>

Date of birth (YYYY-MM-DD)

address
string

Current street address

city
string

Current city

state
string

Two-letter state code

zip
string

ZIP code

locationName
string

Name of current location (e.g., hospital, facility name)

currentLocationType
string
Enum: "Home" "Hospital" "Skilled Nursing" "Assisted Living" "Memory Care" "Independent Living" "Rehabilitation" "Other"

Type of current location

dischargeDate
string <date>

Expected discharge date if applicable (YYYY-MM-DD)

bestLocationAddress
string

Preferred location address

bestLocationCity
string

Preferred city

bestLocationState
string

Preferred state (two-letter code)

bestLocationZip
string

Preferred ZIP code

monthlyBudget
number

Monthly budget in dollars

Array of objects (Contact)

Related contacts (family, friends, POA, etc.)

Array of objects (CustomField)

Answers to tenant-specific custom questions.

How to use:

  1. Call /client/custom-questions to discover available questions
  2. Use the question's key property as the field key
  3. Provide values in the format expected by the question type:
    • text: "Some text response"
    • boolean: true or false
    • number: 1234
    • date: "2024-03-15" (ISO date)
    • multi-select: ["option1", "option2"] (array of prompt keys)
    • range: {"min": 3000, "max": 5000}

Examples:

[
  { "key": "owns_home", "value": true },
  { "key": "assistance_needed", "value": ["grooming", "bathing"] },
  { "key": "amenity_notes", "value": "Needs wheelchair accessible room" }
]
notes
string

General notes about the client

assignedUserId
string <uuid>

ID of the user assigned to this client. Use /users endpoint to get available user IDs.

To explicitly mark a client as unassigned, use the empty UUID: 00000000-0000-0000-0000-000000000000

referralContactId
string <uuid>

ID of the referral contact. Use /referral-contacts endpoint to get or create referral contacts.

referralOrganizationId
string <uuid>

ID of the referral organization. Use /referral-organizations endpoint to get or create referral organizations.

Responses

Request samples

Content type
application/json
Example
{
  • "statusId": "550e8400-e29b-41d4-a716-446655440000"
}

Response samples

Content type
application/json
{
  • "id": "660e8400-e29b-41d4-a716-446655440001",
  • "serial": 1234
}

List clients

Returns all clients visible to your API key based on permissions.

Permissions

  • Admin users can see all clients in their tenant
  • Restricted users can only see clients they are assigned to or collaborating on

Filtering

You can filter clients using the following query parameters:

Filter by assigned user (assignedUserId):

  • Omit the parameter to return all visible clients
  • Provide a valid user UUID to filter by that specific assignee
  • Use the empty UUID (00000000-0000-0000-0000-000000000000) to return only unassigned clients

Filter by update time (updatedAfter):

  • Provide an ISO 8601 timestamp to return only clients updated after that time
  • Example: ?updatedAfter=2024-01-15T14:30:00Z

Filters can be combined: ?assignedUserId=UUID&updatedAfter=2024-01-15T14:30:00Z

Response

Returns an array of client objects sorted by most recently updated first. Only core client fields are included - related entities like contacts and custom fields are excluded. To retrieve these fields including contacts, use the GET /clients/{id} endpoint to fetch individual client details.

Authorizations:
ApiKeyAuth
query Parameters
assignedUserId
string <uuid>
Examples:
  • assignedUserId=770e8400-e29b-41d4-a716-446655440002 - Filter by specific user
  • assignedUserId=00000000-0000-0000-0000-000000000000 - Get only unassigned clients

Filter clients by assigned user.

  • Provide a valid user UUID to filter by that specific assignee
  • Use the empty UUID (00000000-0000-0000-0000-000000000000) to return only unassigned clients
  • Omit this parameter to return all visible clients
updatedAfter
string <date-time>
Example: updatedAfter=2024-01-15T14:30:00Z

Filter clients by update time. Returns only clients updated after the specified timestamp.

  • Provide an ISO 8601 timestamp (e.g., 2024-01-15T14:30:00Z)
  • Omit this parameter to return clients regardless of update time

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get a client by ID

Returns detailed information for a specific client.

Permissions

  • Admin users can view any client in their tenant
  • Restricted users can only view clients they are assigned to or collaborating on

Response

Returns the client object with all core fields, custom field answers, and related contacts.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>
Example: 660e8400-e29b-41d4-a716-446655440001

Client ID (UUID)

Responses

Response samples

Content type
application/json
{
  • "id": "660e8400-e29b-41d4-a716-446655440001",
  • "serial": 1234,
  • "name": "John Smith",
  • "email": "john.smith@example.com",
  • "phone": "+14155551234",
  • "preferredName": "Johnny",
  • "gender": "Male",
  • "maritalStatus": "Widowed",
  • "dateOfBirth": "1945-06-15",
  • "address": "456 Oak Ave",
  • "city": "Portland",
  • "state": "OR",
  • "zip": "97201",
  • "locationName": "Providence Medical Center",
  • "currentLocationType": "Hospital",
  • "dischargeDate": "2024-02-15",
  • "bestLocationCity": "Portland",
  • "bestLocationState": "OR",
  • "monthlyBudget": 4500,
  • "statusId": "550e8400-e29b-41d4-a716-446655440000",
  • "assignedUserId": "770e8400-e29b-41d4-a716-446655440002",
  • "regionId": "880e8400-e29b-41d4-a716-446655440003",
  • "updatedAt": "2024-01-15T14:30:00Z",
  • "createdAt": "2024-01-10T10:00:00Z",
  • "customFields": [
    ],
  • "contacts": [
    ]
}

Update a client

Updates an existing client record with the provided fields.

Partial Updates

This endpoint supports partial updates - you only need to provide the fields you want to change. All fields are optional.

Important Notes

  • customFields CAN be updated - only the custom fields you provide will be updated, others remain unchanged
  • The response includes the updated client with all fields including customFields
  • Custom fields in the response will show all saved values (both updated and unchanged)

Permissions

  • Admin users can update any client in their tenant
  • Restricted users can only update clients they are assigned to or collaborating on

Validation

All field validations from client creation apply:

  • Email must be valid format
  • Dates must be in YYYY-MM-DD format
  • Enum fields must match allowed values
  • UUIDs must be valid and reference existing entities
Authorizations:
ApiKeyAuth
path Parameters
id
required
string <uuid>
Example: 660e8400-e29b-41d4-a716-446655440001

Client ID (UUID)

Request Body schema: application/json
required
statusId
string <uuid>

Update the client status

name
string

Update client's full name

preferredName
string

Update preferred name or nickname

email
string <email>

Update client's email address

phone
string

Update client's phone number (will be normalized to E.164 format)

gender
string
Enum: "Female" "Male" "Other"

Update client's gender

maritalStatus
string
Enum: "Single" "Married" "Divorced" "Widowed" "Separated" "Domestic Partnership"

Update marital status

dateOfBirth
string <date>

Update date of birth (YYYY-MM-DD)

address
string

Update current street address

city
string

Update current city

state
string

Update two-letter state code

zip
string

Update ZIP code

locationName
string

Update name of current location

currentLocationType
string
Enum: "Home" "Hospital" "Skilled Nursing" "Assisted Living" "Memory Care" "Independent Living" "Rehabilitation" "Other"

Update type of current location

dischargeDate
string <date>

Update expected discharge date if applicable (YYYY-MM-DD)

bestLocationAddress
string

Update preferred location address

bestLocationCity
string

Update preferred city

bestLocationState
string

Update preferred state (two-letter code)

bestLocationZip
string

Update preferred ZIP code

monthlyBudget
number

Update monthly budget in dollars

assignedUserId
string <uuid>

Update the assigned user ID. Use the empty UUID (00000000-0000-0000-0000-000000000000) to unassign.

referralContactId
string <uuid>

Update the referral contact ID

referralOrganizationId
string <uuid>

Update the referral organization ID

Array of objects (CustomField)

Update custom field answers. Only the custom fields provided in this array will be updated.

Partial Update Behavior:

  • Only custom fields included in the request will be updated
  • Other existing custom fields will remain unchanged
  • To update multiple fields, include all fields you want to change

Format: Use the same format as CreateClientRequest - provide the question key and value. All validation rules from creation apply.

Responses

Request samples

Content type
application/json
Example
{
  • "statusId": "550e8400-e29b-41d4-a716-446655440001"
}

Response samples

Content type
application/json
{
  • "id": "660e8400-e29b-41d4-a716-446655440001",
  • "serial": 1234,
  • "name": "John Michael Smith",
  • "email": "mike.smith@example.com",
  • "phone": "+15551234567",
  • "preferredName": "Mike",
  • "gender": "Male",
  • "maritalStatus": "Widowed",
  • "dateOfBirth": "1945-06-15",
  • "address": "456 Oak Ave",
  • "city": "Portland",
  • "state": "OR",
  • "zip": "97201",
  • "monthlyBudget": 5500,
  • "statusId": "550e8400-e29b-41d4-a716-446655440002",
  • "assignedUserId": "770e8400-e29b-41d4-a716-446655440002",
  • "regionId": "880e8400-e29b-41d4-a716-446655440003",
  • "updatedAt": "2024-01-15T16:45:00Z",
  • "createdAt": "2024-01-10T10:00:00Z",
  • "customFields": [
    ]
}

Configuration

Operations for retrieving tenant-specific configuration

List custom questions for clients

Returns all custom questions configured for clients in your tenant. Use these questions to understand what custom fields are available when creating clients.

For multi-select questions, use the prompt keys in your answers array. For other question types, provide the appropriate value type (text, number, boolean, date).

Authorizations:
ApiKeyAuth
query Parameters
category
string
Example: category=preferences

Filter questions by category

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

User Management

Operations for managing users and assignments

List users for assignment

Returns a list of users that can be assigned to clients. Use the returned user IDs in the assignedUserId field when creating clients.

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Referral Sources

Operations for managing referral contacts and organizations

List referral contacts

Returns all referral contacts for your tenant

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a referral contact

Creates a new referral contact that can be used when creating clients

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string

Full name of the contact

email
string <email>

Email address

phone
string

Phone number

organizationId
string <uuid>

ID of the organization this contact belongs to. Must be a valid organization ID that you have access to.

title
string

Job title or role

Responses

Request samples

Content type
application/json
{
  • "name": "Dr. Sarah Wilson",
  • "email": "sarah.wilson@hospital.com",
  • "phone": "(555) 123-4567",
  • "organizationId": "990e8400-e29b-41d4-a716-446655440007",
  • "title": "Discharge Planner"
}

Response samples

Content type
application/json
{
  • "id": "880e8400-e29b-41d4-a716-446655440006"
}

List referral organizations

Returns all referral organizations for your tenant

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a referral organization

Creates a new referral organization that can be used when creating clients

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
name
required
string

Organization name

phone
string

Main phone number

website
string

Website URL

address
string

Street address

city
string
state
string

Two-letter state code

zip
string

Responses

Request samples

Content type
application/json
{
  • "name": "Seattle General Hospital",
  • "phone": "(555) 234-5678",
  • "website": "https://www.hospital.com",
  • "address": "123 Medical Center Dr",
  • "city": "Seattle",
  • "state": "WA",
  • "zip": "98101"
}

Response samples

Content type
application/json
{
  • "id": "990e8400-e29b-41d4-a716-446655440007"
}