Integrate with Twyll using Flat Files
Integrating external data into Twyll is simple and efficient when using CSV files. This guide will walk you through the steps to prepare and submit your data for smooth integration. For more details on the process, refer to our Integration Methods article.
The sections below outline the required, recommended, and optional fields for different data objects, along with guidelines to help you prepare your data files effectively.
File Submission Methods
You can submit your data to Zipper in one of two ways:
- Combined File: Submit a single CSV file with all the headers for each object type you're integrating. This is ideal for managing all your data in one file.
- Separate Files: Use individual CSV files for each resource type (e.g. one for clients and one for staff). This helps organize your data by category.
In both methods, include a resource_type column to indicate the type of resource each row represents (client, guardian, staff or, session). Each submitted file can contain multiple rows, one per entity/record.
All flat files must be submitted to Zipper through an SFTP site provided by the SpectrumAi team. Refer to our Integration Methods article for more details.
Field Requirements Key
- Required fields are in bold and dark blue. These must be provided for successful integration.
- Recommended fields are in italics and dark green. These are not mandatory, but they ensure optimal functionality within Twyll.
- Optional fields are in regular text. Include these fields if they are relevant to your data.
Clients
| Field Name | Description |
|---|---|
| first_name | The client's first name. |
| last_name | The client's last name. |
| preferred_name | The client's preferred name, if different from their first name. |
| middle_name | The client's middle name. |
| gender | The client's gender. |
| date_of_birth | The client's date of birth (format: YYYY-MM-DD). |
| race | The client's race. |
| ethnicity | The client's ethnicity. |
| Address Information | |
| street_1 | The first line of the client's street address. |
| street_2 | The second line of the client's street address (e.g., apartment or suite number). |
| city | The city where the client resides. |
| state | The state or province where the client resides. |
| zip | The ZIP or postal code for the client's address. |
| pos_code | The Place of Service code indicating where services are provided. |
| external_id | A unique external identifier for the client, used to match records across systems. |
Guardians
| Field Name | Description |
|---|---|
| first_name | The guardian's first name. |
| preferred_name | The guardian's preferred name. |
| last_name | The guardian's last name. |
| date_of_birth | The guardian's date of birth (format: YYYY-MM-DD). |
| The guardian's email address. | |
| phone | The guardian's phone number. |
| Address Information | |
| street_1 | The first line of the guardian's street address. |
| street_2 | The second line of the guardian's street address. |
| city | The city where the guardian resides. |
| state | The state or province where the guardian resides. |
| zip | The ZIP or postal code for the guardian's address. |
| language | The guardian's preferred language. |
| note | Any additional notes about the guardian. |
| clients | A comma-separated list of associated client external_ids. |
Staff
| Field Name | Description |
|---|---|
| The staff member's email address, used for login and communication. | |
| status | The employment status of the staff member (e.g., active, inactive). |
| clinic | The clinic identifier where the staff member works. Defaults to the primary clinic if only one exists. |
| role | The staff member's role within the organization (e.g., therapist, administrator). |
| first_name | The staff member's first name. |
| preferred_name | The staff member's preferred name. |
| last_name | The staff member's last name. |
| phone | The staff member's contact phone number. |
| gender | The staff member's gender. |
| hire_date | The date the staff member was hired (format: YYYY-MM-DD). |
| languages | A comma-separated list of languages the staff member speaks. |
| Credential Information | |
| credentials | A comma-separated list of the staff member's professional credentials. |
| credential_date | A comma-separated list of dates when each credential was obtained (aligns with credentials). |
| recertification_date | The date when the staff member's credentials were last re-certified. |
| external_id | A unique external identifier for the staff member, used for matching records. |
Sessions
| Field Name | Description |
|---|---|
| client_id | The client's external_id or another unique identifier. |
| staff | The staff member's external_id or another unique identifier. |
| session_type | The type of session (e.g., therapy, consultation). |
| status | The session status (e.g., scheduled, canceled, completed). |
| pos_code | The Place of Service code for the session. |
| scheduled_start | The scheduled start time of the session (format: YYYY-MM-DDTHH:MM:SS). |
| scheduled_end | The scheduled end time of the session (format: YYYY-MM-DDTHH:MM:SS). |
| funder | The funding source for the session (e.g., insurance provider). |
| procedure_code | The procedure code associated with the session, for billing purposes. |
| service_description | A description of the service provided during the session. |
| external_id | A unique external identifier for the session, used to match records. |
For further details on available fields and integration options, including allowed values, please consult our API Specifications. Our support team is here to help with any questions.
Comments
0 commentsPlease sign in to leave a comment.