WelcomeHome Software

WelcomeHome API Documentation

The WelcomeHome API requires an Authorization header with a token for authentication, supports endpoints to list and create activities with optional filters and pagination, allows testing tokens via `/api/ping`, and includes detailed instructions for creating calendar-linked activities with time zone and time formatting options.

Authorization Request Header

When making requests, include your API Token in an Authorization request header like so:

Authorization: Token token={your_token_here}

You can test your API token using the /api/ping endpoint. For example:

curl https://crm.welcomehomesoftware.com/api/ping -H "Authorization: Token token={token_here}"

A successful authentication returns response code 200 and a JSON body describing the account the token provides access to, e.g.:

{"account_id":2,"lead_source_id":null}

A failed authentication returns response code 401 and the message:

{"error":"Bad credentials"}

A failed authorization returns response code 403 and the message:

{"error":"Not authorized to perform this action"}

Activities

List Activities

Endpoint: GET /activities

Query Parameters:

  • limit (integer): Number of records to return per page. Default: 10. Maximum: 100.
  • filters[activity_type_id] (integer): Activity Type ID to search on.
  • filters[created_at_after] (string): e.g. "2000-01-01T00:00:00Z"
  • filters[created_at_before] (string): e.g. "2000-01-01T00:00:00Z"
  • filters[updated_at_after] (string): e.g. "2000-01-01T00:00:00Z"
  • filters[updated_at_before] (string): e.g. "2000-01-01T00:00:00Z"

Response: 200 OK, returns a list of activities.

List Prospect Activities

Endpoint: GET /prospects/{prospect_id}/activities

Response: 200 OK, returns a list of activities for the given prospect.

Create Activity

To add a start and end time, "add_to_calendar": true must be passed along with time_zone, calendar_event_start_time, and calendar_event_end_time. calendar_event_start_time and calendar_event_end_time also support Meridian indicators like "3:00 PM". The standard North American time zones are:

  • Eastern Time (US & Canada)
  • Central Time (US & Canada)
  • Mountain Time (US & Canada)
  • Pacific Time (US & Canada)
  • Alaska
  • Arizona
  • Hawaii

Endpoint: POST /prospects/{prospect_id}/activities

Request Body:

  • activity (object)

Response: 200 OK, returns the created activity.

Update Prospect Activity

Same requirements as Create Activity for calendar fields.

Endpoint: PUT /prospects/{prospect_id}/activities/{activity_id}

Request Body:

  • activity (object)

Response: 200 OK, returns the updated activity.

List Activity Types

Endpoint: GET /activity_types

Response: 200 OK, returns a list of activity types.

Care Types

List Care Types

Endpoint: GET /care_types

Response: 200 OK, returns a list of care types.

Communities

List Communities

Endpoint: GET /communities

Response: 200 OK, returns a list of communities.

Events

List Events

Endpoint: GET /events

Query Parameters:

  • limit (integer): Number of records per page. Default: 10. Maximum: 100.
  • filters[community_id] (integer)
  • filters[created_at_after] (string)
  • filters[created_at_before] (string)
  • filters[updated_at_after] (string)
  • filters[updated_at_before] (string)

Response: 200 OK, returns a list of events.

Create Event

Endpoint: POST /events

Request Body:

  • event (object)

Response: 201 Created, returns the created event.

RSVP to an Event

This endpoint updates an RSVP status of an invite that corresponds to a person's email or ID, for the given event.

  • Either an email or a person ID is required.
  • If both are present, only the person ID will be used.
  • If the email is used for multiple people invited to the event, all corresponding invites will be updated.
  • If an email or person ID for an uninvited person is submitted, that person's Prospect or Referrer record will be invited to the event, and the invite will be updated.
  • If an email or person ID is submitted that does not exist, returns 404.
  • If no status parameter or neither email nor person ID parameters are submitted, returns 422.

Endpoint: POST /events/{event_id}/rsvps

Request Body:

  • email (string)
  • status (string, required): Enum: "pending_response", "accepted", "declined", "not_sure"
  • person_id (integer)

Responses:

  • 200: success
  • 404: not found
  • 422: unprocessable entity

Exports

Live, paginated CSV data

This endpoint provides live, paginated bulk export capability. It is the most efficient way to get a full data dump out of WelcomeHome. It can also be used to poll for changes by filtering based on updated_at.

Typical usage:

  • Perform an initial pull of each table, paging through all results to get an entire copy of the dataset.
  • Periodically re-poll, but using updated_at_after to retrieve any changes made since the last poll.

By default, this endpoint returns 1000 results per page. To retrieve all data, request each page until all pages have been fetched. If the response has been paginated and there are more records to retrieve, the Link header will be present with a URL for the next page.

A given cursor can only be used 3 times within a single minute.

All timestamps are in UTC unless otherwise specified.

Endpoint: GET /exports/community/{community_id}/table/{table}

Path Parameters:

  • community_id (string, required): A community ID or all for all communities
  • table (string, required): The table to export. One of:
    • Organizations
    • Referrers
    • Prospects
    • ProspectFields
    • Residents
    • Influencers
    • Activities
    • ExternalReferences
    • Units
    • HousingContracts
    • DepositTransactions
    • MarketingTouchpoints
    • ServiceAgreements
    • Traits
    • Users
    • WaitlistEntries

Query Parameters:

  • sort_by (string): Column to sort by: updated_at (default), created_at
  • limit (integer): Number of records per page. Default: 1000. Maximum: 10000.
  • filters[created_at_after] (string)
  • filters[created_at_before] (string)
  • filters[updated_at_after] (string)
  • filters[updated_at_before] (string)

Response: 200 OK, returns CSV data.

Daily snapshot of CSV data

This endpoint provides access to unpaginated, daily snapshots of the same content that can be retrieved from the live, paginated export endpoint. Snapshots are generated nightly. Requires an API Token with access to all communities.

Endpoint: GET /exports/daily_snapshots/table/{table}

Path Parameters:

  • table (string, required): The table to export (see above for options)

Query Parameters:

  • direct (string): Set to true to receive the file content directly instead of a redirect.

Responses:

  • 200: CSV content (when direct=true)
  • 301: Redirect to CSV location (default)

Floor Plans

List Floor Plans

Endpoint: GET /floor_plans

Query Parameters:

  • filters[community_id] (integer)

Response: 200 OK, returns a list of floor plans.

Housing Contracts

List Housing Contracts

Endpoint: GET /housing_contracts

Query Parameters:

  • limit (integer): Number of records per page. Default: 10. Maximum: 100.
  • filters[created_at_after] (string)
  • filters[created_at_before] (string)
  • filters[updated_at_after] (string)
  • filters[updated_at_before] (string)
  • filters[move_in_date_before] (string)
  • filters[move_in_date_after] (string)
  • filters[prospect_id] (integer)
  • filters[resident_id] (integer)
  • filters[community_id] (integer)

Response: 200 OK, returns a list of housing contracts.

Influencers

Show Influencer

Endpoint: GET /influencers/{id}

Path Parameters:

  • id (integer, required)

Response: 200 OK, returns influencer details.

Update Influencer

Allows updating certain data points for influencers: birthdate, age, gender, and address.

Endpoint: PUT /influencers/{id}

Request Body:

  • influencer (object)

Response: 200 OK, returns updated influencer.

Lead Sources

List Lead Sources

Endpoint: GET /lead_sources

Response: 200 OK, returns a list of lead sources.

Privacy Levels

List Privacy Levels

Endpoint: GET /privacy_levels

Query Parameters:

  • filters[community_id] (integer)

Response: 200 OK, returns a list of privacy levels.

Prospect Fields

List Prospect Fields

Endpoint: GET /prospect_fields

Response: 200 OK, returns a list of prospect fields.

Prospects

Create Prospect

Allows you to add new prospects into WelcomeHome. When you add a new prospect, it appears on top of a new prospects dashboard. Notifications are sent to users via email/mobile push as per their preferences.

A prospect record must have at least one influencer or resident. At least one of those records must have a first or last name. All other fields are optional and should be omitted if intended to be left blank.

Endpoint: POST /prospects

Request Body:

  • prospect (object)

Response: 201 Created, returns the created prospect.