Activated Insights SyncStream API (1.0.0)

The SyncStream API is a RESTful API that allows you to integrate with Activated Insights services.

Our API has predictable resource-oriented URLs, accepts json-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The SyncStream API serves as a single channel for importing Caregivers (as Practitioners) and Clients (as Patients) into one or more Activated Insights products without the need for direct-to-product connections for each product.

The mechanism is primarily intended for PUT (upsert) actions. Bulk reading of records for import should still be conducted in individual products because each product has an independent process and schedule for importing data from this channel. A GET operation is available on the /employees and /patients resources to retrieve basic details about events previously sent through this channel.

This API supports sending individual records or Bundles up to size 10 records per Bundle. For best performance, using Bundles is recommended as it reduces the overall number of requests. Sending records in Bundles or individually has identical effect on the import.

Using a Batch Identifier

There may be times where you want to uniquely identify a batch of records. This can achieved by including an AI-Batch-ID identifier in the record. For Example:

{
  "resourceType": "Practitioner",
  "id": "123",
  "identifier": [{"system": "AI-Batch-ID", "value": "batch-001"}]
}

Records are delivered to downstream products in batches based on the AI-Batch-ID.

Records received without an AI-Batch-ID will be imported as individual create/update operations. For example, if the requirement is to send a full snapshot of an employee roster in a single batch then the AI-Batch-ID can be used to group the records together. If the requirement is to send a streaming series of independent changes then you should omit AI-Batch-ID from the records.

The SyncStream API uses OAuth2 Client Credentials Flow.

Your Client ID and Client Secret will be provided by the Activated Insights implementations team.

Token URL

POST https://sso.homecarepulse.com/auth/realms/hcp/protocol/openid-connect/token

• Token lifetime: (default) 3 hours
• Scope: No scopes are required for this API
• The token response includes an expires_in field indicating the number of seconds until the token expires. We recommend refreshing the token proactively before it expires to avoid authentication errors.
• If your token expires, you will receive a 401 Unauthorized status code when making API requests.

How to retrieve an access token

Example: cURL

$ curl -X POST \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  https://sso.homecarepulse.com/auth/realms/hcp/protocol/openid-connect/token

Example: Python3 (requests)

import requests

token_url = "https://sso.homecarepulse.com/auth/realms/hcp/protocol/openid-connect/token"
data = {
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
}

response = requests.post(token_url, data=data)
print(response.json())

Response format

{
  "access_token": "…",
  "expires_in": 300,
  "token_type": "Bearer"
}

Using the access token

Include the token in the Authorization header:

Authorization: Bearer {access_token}

The SyncStream API has a rate limit of 2 requests per second and 20k requests per day. If you exceed this limit, you will receive a 429 status code.

Example response

{
  "code": "RATE_LIMIT_ERROR",
  "message": "Rate limit exceeded"
}

The meta.tag field on Practitioner and Patient resources can be used to include additional information about the record that may be relevant for downstream products. Refer to the following list as a reference of common meta tags used by our products, but please work with your Activated Insights implementation team to determine the specific meta tags that are relevant for your use case and products.

• admission: a date in YYYY-MM-DD format indicating when a patient was admitted to a facility.
• applicationDate: a date in YYYY-MM-DD format indicating when an employee applied for a role.
• dischargeReason: a string indicating the reason for a patient's discharge.
• discharge: a date in YYYY-MM-DD format indicating when a patient was discharged from a facility.
• doNotCall: a true/false boolean indicating whether a patient should not be contacted by phone.
• hired: a date in YYYY-MM-DD format indicating when an employee was hired.
• jobTitle: a string indicating an employee's job title.
• payerGroupName: indicates the primary payer group for a patient.
• payerGroupNumber: indicates the primary payer group for a patient.
• payerId: indicates the primary payer ID for a patient.
• payerName: indicates the primary payer name for a patient.
• payerPlanId: indicates the primary payer plan ID for a patient.
• ou1-ou10: custom organizational unit tags commonly used to indicate location or department or grouping within an organization. Examples include division, region, district, office, teeam, etc. The specific use of these tags varies widely across implementations.

Employee / Practitioner operations

Patient / Client operations