![Holistiplan Logo (800x200 px).webp]](https://help.holistiplan.com/hs-fs/hubfs/Holistiplan%20Logo%20(800x200%20px).webp?width=160&height=40&name=Holistiplan%20Logo%20(800x200%20px).webp){kind=small}
Holistiplan API Endpoint Reference
The interactive API documentation is the source of truth for parameters and schemas. Use the categories below to understand how endpoints relate.
Jump to a section
- Users & permissions
- Household & client management
- Document intake
- Tax planning data
- Document export
- Reporting
Users & permissions
Manage firm structure, advisor accounts, and access permissions.
Subsidiaries
Read + write. Manage firm subsidiary records, including names and branding. Create, update, and delete subsidiaries, and assign households to a subsidiary.
Note: Write operations require firm admin access.
Units
Read + write. Manage organizational units within a firm, including which advisors and households belong to each unit.
Note: Write operations require firm admin access.
Firm Permission Groups
Read only. Retrieve the permission groups available to a firm. Use group IDs when creating or updating users.
Users
Read + write. Create, update, activate, deactivate, and delete advisor accounts. You can also reset passwords and send invitations.
Note: You cannot delete your own account.
Household & client management
Manage the core household and client records used by most integrations.
For CRM integrations, use crm_key on households and clients and external_reference on households to associate records with external CRM systems.
Households
Read + write. Create, retrieve, update, and delete households. Records can include advisors, units, CRM IDs, billing status, tags, tax return years, and activity metadata.
Common actions:
POST /households/create_or_update_many/POST /households/{id}/deactivate/POST /households/{id}/reactivate/
Note: is_billed_household is read-only. Use the deactivate and reactivate actions to change the household's active billing state.
Clients
Read + write. Manage individuals within a household, including names, contact information, and CRM keys.
Bulk create, update, and delete operations are supported.
Document intake
Upload tax documents to Holistiplan and monitor processing status.
Tax Returns
Read + write. Create tax return records, upload PDFs, and monitor processing status.
Common action: POST /tax_returns/{id}/multipart_upload/
Processing statuses: awaitingFile, processing, error, done, needsReview, ignore
Note: Tax return PDFs must be 50 MB or smaller and can only be uploaded once per record.
Client Upload Links
Read + write. Generate secure links for clients to upload documents. Create individual or bulk links and refresh expired links.
Common actions:
POST /client_upload_links/create_many/POST /client_upload_links/{id}/refresh_link/
Typical workflow: Create an upload link or upload a tax return → monitor processing → retrieve processed data through Income Tax.
Tax planning data
Access structured tax data after documents have been processed.
Income Tax
Read only + selected actions. Retrieve processed tax data from uploaded returns, including income, deductions, taxpayers, and tax year information.
Common action: POST /income_tax/{id}/create_tax_report/ to create a Tax Report from an Income Tax record.
Scenario Analyses
Read only. Retrieve tax scenario data for what-if analyses. Filter by household, taxpayers, and tax year.
Document export
Retrieve generated reports and PDF deliverables.
Tax Reports
Read only + selected actions. List and retrieve Tax Reports created from processed Income Tax records.
Tax Reports can be queued for PDF generation.
Roth Projections
Read only + selected actions. List and retrieve Roth conversion projection reports and queue PDFs for download.
Tax Letters
Read only + selected actions. Retrieve tax letter status by household and year. Queue individual PDFs or a ZIP containing letters for up to 100 households.
Common action: POST .../queue_zip_of_snapshots/ to queue a ZIP of tax letter PDFs for up to 100 households.
PDF Snapshots
Read only + selected actions. Monitor queued PDF jobs and download completed PDFs.
Typical workflow: Queue a PDF from Tax Reports, Roth Projections, or Tax Letters → save the snapshot_job_id → poll the snapshot status → use the download action when the status is success.
Reporting
Access usage, advisor activity, household activity, and affiliation data.
Affiliation Firms
Read only. Retrieve firms that share your affiliation, including household counts, subscription information, renewal dates, and firm status.
Note: Available to firms in an affiliation network.
Usage
Read only. Retrieve upload usage records by firm, advisor, and source.
Sources include tax, tax_status, insurance, corelogic, and other.
User Activity Report
Read only. Retrieve advisor feature usage over time, including scenario analysis, Tax Reports, explainers, Tax Letters, and insurance uploads.
Note: Requires the allow_user_activity_report firm setting.
Household Activity
Read only. Retrieve an audit trail of household-level actions, including the user, timestamp, household, and action.
Tip: User Activity Report tracks advisor feature usage, while Household Activity provides an audit trail of actions performed on household records.
Additional resources
expand query parameter
Many endpoints support the expand query parameter to include related objects in the response. Supported values vary by endpoint; see the interactive API documentation for details.
Don't see what you're looking for?
If you don't see an endpoint or API capability you need, email support@holistiplan.com with a brief description of what you're trying to accomplish. Our team can help determine whether an existing endpoint can meet your needs or whether your request should be considered for future API development.