Socotra
Getting Started
Introduction to Socotra
Overview
What is Socotra?
What is Socotra Insurance Suite?
What is the Getting Started with Socotra learning path?
Have questions?
Ready for the next module?
Log into Socotra
Overview
What will I learn?
What will I need?
Key concepts
What is a business account?
Ready to begin?
Steps
Recap
Ready for the next module?
Create a tenant configuration file
Overview
What will I learn?
What will I need?
Note about JSON
Key concepts
What is a tenant configuration file?
What is a tenant?
How is a tenant configuration file structured?
What is an insurance product?
What is an account holder?
What is an element?
Visualizing an insurance product configuration
Ready to begin?
Part 1 - Creating a configuration file
Part 2 - Basic editing of the tenant configuration file
View the configuration file
Concept - Attributes
Concept - Default attributes
Edit the default attributes
Concept - Attribute types
Part 3 - Advanced editing of the tenant configuration file
View the Products menu
Making changes to the product
Recap
Ready for the next module?
Overview - Tenants
What is a tenant?
Tenants page
Tenant configuration page
Users
Resources
Resource instances
Resource groups
Ready for the next module?
Create a tenant
Steps
Ready for the next module?
Set up Postman to use the Socotra API
Overview
What will I learn?
What will I need?
Issues with your credentials?
Ready to begin?
Steps
Part 1 - Set up your collection and environment
Part 2 - Set up your environment
Part 3 - Authenticate with Socotra
Make a request to test your authentication
Troubleshooting
Recap
Ready for the next module?
Create an account
Key concepts
What is an account?
What is the process for creating an account?
API steps
What will I need?
Create an account
Update an account
Validate an account
Web app steps
Recap
Ready for the next module?
Execute a quote to bind
Overview
What will I learn?
What will I need?
Key concepts
What is a quote?
What is a policy?
Life cycle of a quote
Resetting a quote
Atypical quote states
Ready to begin?
Steps
Part 1 - Create a quote
Request body breakdown
Part 2 - Validate the quote
Part 3 - Price the quote
Part 4 - Underwrite the quote
Part 5 - Accept the quote
Part 6 - Issue the quote
Recap
Ready for the next module?
Execute policy transactions
Overview
What will I learn in this tutorial?
What will I need?
Key concepts
What is a policy?
What are terms and segments?
Terms
Segments
What is a policy transaction?
Example scenarios
Example 1 - Changing a policy
Example 2 - Renewing a policy
Example 3 - Canceling a policy
Tutorials
Scenario - Homeowner seeking to modify home insurance coverage
Tutorial 1 - Making a change to a policy
1.1 - Locating customer’s account number in Postman
1.2 - Locating customer’s policy in Postman
1.3 - Retrieving customer’s policy details
1.4 - Creating a change transaction
1.5 - Issuing a change transaction
1.6 - Viewing the changed policy
Tutorial 2 - Renewing a policy
Tutorial 3 - Canceling a policy
Tutorial 4 - Reinstating a policy
Ready for the next module?
Trigger billing, pay, and invoices
Overview
What will I learn?
What will I need?
What is the billing life cycle?
Walkthrough the billing life cycle
Stage 1: Quote is issued (via API)
Stage 2: System generates an installment lattice
Stage 3: System generates installments
Stage 4: System generates invoice(s)
Stage 5: Payment is created (via API)
Stage 6: Payment is posted to invoice (via API)
Socotra sample Postman collection and environment
Set up and use the Config SDK for tenant configuration
Overview
What is the Config SDK?
Advantages to using the Config SDK
Advantage example: Streamlining data typing
Advantage example: Generating Java classes
What will I learn?
What will I need?
Steps
Part 1 - Create a Personal Access Token
Part 2 - Download and configure the Config SDK
Part 3 - Fetch your tenant’s config
Part 4 - Update and validate the configuration
Part 5 - Write a plugin
Part 6 - Write tests
Create a user
Key concepts
Users
Admins
Ready to begin?
Feature Guide
Business Accounts
Overview
See also
Accounts
Overview
Configuring accounts
Example: BaseAccount
Example: CommercialAccount
Example: ConsumerAccount
Account states
Limiting products to certain account types
Extension data
See also
First Notice of Loss (“FNOL”)
Overview
Configuration
State Flow and Validation
Versioning
Promotion
Contact Management
Overview
Configuring Contacts
Contact States
Tutorial
Merging Contacts
Searchability
Quotation Topic Index
Quotes
Quote State Flow
Standard Flow
Atypical States
Quote Reset
Time Zones
Currencies
Error Handling
See Also
Quick Quotes
Overview
Workflow
Quotation
Discard
See Also
Policy Management Topic Index
Policy Transactions
Structure
Provisional Transactions
Basic Transactions
Process
Transaction Reset
See Also
Policy Transaction Stack
Workflow
Transaction Data
Documents
Validation
See Also
Policy Elements
Overview
Categories and Types
Example
Quantifiers
Coverage Terms
Data Extensions
See Also
Policy Status
Overview
Obtaining Policy Status
API
Event Stream
Coverage Terms
Overview
Configuration
Sample Configuration
Elements with Coverage Terms
Creation
Update
Default Coverage Term Options and Values
Plugins
Out of Sequence Transactions
Overview
High-Level Approach
Static Locators
Intervening Out-of-Sequence Transactions
Reversals
See Also
Transaction Branching and Invalidation
Example
Details
Elements
Auto-Rebasing
See Also
Reinstatement
Overview
Behavior
Reinstatement After Multiple Cancellations
Reinstatement with a Gap
Renewal Management and Auto-Renewal
Overview
Manual Renewal
Auto-Renewal
Auto-Renewal States
Auto-Renewal Plugin
Manual Renewal Operations on an Auto-Renewal
Cancellations and Auto-Renew
Do Not Renew
Renewal with a Gap
See Also
Billing Topic Index
Installment Lattices
Overview
Structure
Process
See Also
Installment Settings
Overview
Settings List
Resolving Settings
Quotes Process
Quotes Example
Policy Transactions Process
Account Preferences
Validation
Persistence
Default Settings
See Also
Invoicing
Overview
Structure
Due Times
Invoice Rendering
See Also
Early Invoicing
Overview
Invocation
Behavior
Error Conditions
See Also
Flat Charges
Overview
Configuration
Usage
Flat Charges via Rating
Flat Charges via API
Invoicing Behavior
Delinquency
Payments
Overview
Payments
Financial Instruments
External Cash Transactions
Payment Distribution
Payment Reversals
Aggregate Payments
Example
See Also
Delinquency
Overview
Configuration
Delinquency Onset
Lapse
See Also
Delinquency Events
Overview
Configuration
Operation
See Also
Billing Holds
Overview
Lifecycle
Invoice Holds
Delinquency Holds
See Also
Disbursements
Overview
Lifecycle
Credit Sources
Financial Instruments
Configuration and Data Extensions
Accounting
See Also
Credit Balances
Overview
Usage
See Also
Excess Credits
Overview
Configuration
Process
See Also
Credits from Policy Transactions and Billing Changes
Overview
Example 1: Standard Cancellation
Example 2: Lapse
See Also
Backloading Installments
Overview
Initial State
Lattice Creation
Charge Processing
Invoicing
Results
Financials Topic Index
Charges
Categories
Charge Types
Reference Rates
Data Precision
Durations
Overview
Usage
Configuration
Supported Duration Bases
Daylight Saving Time
Rounding Service
Basic Double-Entry Accounting Primer
Introduction
General Principles
T-Accounts
Transactions
See Also
Simplified Accounting Example
Overview
Summary
See Also
Underwriting
Overview
What is an underwriting plugin?
What is an underwriting flag?
Post-underwriting Evaluation
Evaluation algorithm
Tips
Underwriting status
Example Underwriting Scenario
See also
Documents Topic Index
Document Management
Overview
Document Retrieval
Direct Document Attachment and Modification
Attaching New Documents
Updating Documents
See Also
Dynamic Documents
Template Languages
Velocity Example
Controlling Template Data
Troubleshooting and Template Development
Streamlining the rendering feedback loop
Data Topic Index
Diaries
Overview
Diary Entries
Revisioning
Discard
See Also
Media
Overview
Example
Search
Overview
Example
Request
Response
Requests
Search String Syntax
Filtering
Responses
Relevance
Search Summary
Sample Responses
Configuration
See Also
Security Topic Index
Roles and Permissions
Special Roles
Tenant Access
Available Permissions
Wildcard Patterns
Auth Tokens
See Also
Comprehensive Permissions Listing
See Also
Password Policies
See Also
Migration
Overview
Migration Structure
Bring Your Own Identifiers
Migration Management
Remediation
Reporting Topic Index
Metrics
Overview
API Usage
Aggregations
Filters
Backfill Zero
Metric Definitions
Gross Written Premium
Issued Policies
Priced Quotes
New Business Conversion Rate
Issued Renewals
Expired Policies
Renewal Rate
Data Lake
Getting Started with Socotra Data Lake
Prerequisites
Data Lake Schema
Frequently Asked Questions (FAQ)
Can I connect with Tableau, Microsoft Power BI, or other such analytical tools?
How can I use datetime values in Data Lake?
What is a locator?
What is the relationship between the Data Lake schema and entity representations in the Socotra API?
Why do some tables have an
id
field while others do not?
What version of MariaDB is Data Lake on?
How often is Data Lake data updated?
Are there alternative ways to consume Data Lake data?
Index of Tables
Data Lake Delta Files
Getting Started with Data Lake Delta Files
Overview
Schema Versioning
Pagination
Client Example
File Index API
Sample DeltaFilesGetRequest
Sample DeltaFilesGetResponse
File Retrieval API
See Also
Previews
Overview
Stateful Preview
Stateless Preview
Invoice Preview
Configuration Guide
Configuration General Topics Index
Configuration Deployment
Overview
Configuration Structure
Configuration Validation
Configuration Case Sensitivity
Inheritence Case Sensitivity
See Also
Configuration Redeployment
Overview
Safe Changes
Migratable Changes
Disallowed Changes
Future Functionality
Locking
Retirement
Configuration Bootstrap
Overview
Notes
Bootstrap Directory
Validations
Example
Configuration SDK
Overview
Do I really need an SDK to write and maintain configs?
Getting Started
Get the source control template
Update the config plugin to point at a target tenant
Use tasks as you build your config
Bootstrapping
Quantifiers
Overview
Structure
Element Quantifiers
Coverage Term Quantifiers
Data Extension Quantifiers
Automatic Items
Automatic Elements
Automatic Coverage Terms
Identifiers
Overview
Items with Identifier Names
Rules
Availability
Overview
Configuration
Examples
Setting a product to retire after a certain time
Retiring a product
Making an element available to new policies starting after a certain time
Automatically removing certain coverage terms on policy renewal
Additional Considerations
Inheritance
Non-Policy Entities
Regions
Overview
Use Cases
Configuration
Quote and Policy Regions
Entity Numbering
Overview
Process
Configuration
Prefixes, Suffixes, and Numbering Strings
Additional Characters
Term Numbers
Overriding Automatically Generated Numbers
Fetch
Error Handling
Limitations
See Also
Events
Usage
See Also
Event Definitions
Account Events
Policy Status Events
Quote Events
Transaction Events
Credit Distribution Events
Delinquency Event Events
Delinquency Events
Disbursement Events
Installment Events
Invoice Events
Numbering Events
Payment Events
Shortfall Credit Events
Write Off Events
Event Payloads
See Also
Webhooks
Managing Webhooks
Failure Handling
Security Features
See Also
Data Access Controls
Overview
Enabling Data Access Controls
Configuring Data Fields
Assigning User Data Masks
See Also
Single Sign-On (SSO)
Overview
Step 1: Register Socotra as a New Application in Your Identity Provider
Step 2: Add your Identity Provider to Socotra
Sample request
Step 3: Receive Service Provider (SP) Metadata from Socotra
Sample response
Step 4: Configure Your Identity Provider with Socotra’s SP Metadata
Step 5: Test the SSO Integration
Key SSO Capability Clarifications
Resources Topic Index
Versioned Resource Selection
Overview
Key Concepts
The Selection Time Basis
API and Entity Structure
Runtime Behavior in Plugins
Document Selection
Unmanaged Resources
Usage Example
Data Tables
Overview
Configuration
Limitations
Documents
Overview
Document Scope
Policy Document Workflow
Quotation
Static and Dynamic Documents
Plugins
Policy Document Selection Plugin
Document Data Snapshot Plugin
Data Extensions Topic Index
Data Extensions
Overview
Data Scopes
Data Types
Quantifiers and Arrays
Validation Requirements
Other Data Properties
Comprehensive Properties List
See Also
Data Extension Types
Overview
Built-In Data Types
Date Types
datetime
date
Custom Data Types
Limitations
Extension Data Constraints
Overview
Structure
Configuration
Dependency Maps
Constraint Evaluation API
Constraint Evaluation for Accounts
Referencing Other Elements
Validation
Custom Data Types
Usage
Custom Data Inheritance
Validation
Static Data
Overview
Context and Use Cases
Configuration
Usage - Quotes
Setting Static Data
Fetching Static Data
Usage - Policies
Setting Static Data
Fetching Static Data
Front-End SDK Topics Index
Front-End SDK Overview
Getting Started
Installation
Schemas
Installation
Example Usage
List of Schemas
Components
Typical Installation
Installation With Tailwind and Custom Theme
Example Usage
Components
Utils
Installation
Example Usage
List of Utils
Front-End SDK Guides Topic Index
Authentication with Keycloak and NextAuth.js
Create a new Next.js App
Add NextAuth.js
Add environment variables for local development
(Optional) Add t3-oss/t3-env
Setup Next.js and NextAuth with Keycloak
Define Middleware for protecting routes
Add Logout Functionality
Components Index
AccountForm
Overview
Props
Usage
Customization
Standard Account Form
Creating a New Account
Updating an Existing Account
Customization
Validation
Submitting the Form
QuoteForm
Overview
Props
Usage
Plugins Topic Index
Plugins Overview
Overview
Precommit
Validation
Rating
Underwriting
Document Data Snapshot
Document Selection
Plugin Execution
Plugin Configuration
Precommit and Validation
Data Fetcher
Resource Selector
External API Calls
Precommit
Overview
Plugin Execution
Manual Execution
Account
Quote
Transaction
Payment
Disbursement
Delinquency
Validation
Overview
Plugin Execution
Account
Quote
Rating
Overview
Configuration
Return Object
Underwriting
Overview
Configuration
Return Object
Document Data Snapshot
Overview
Example
Document Selection
Overview
API Guide
Business Account API Index
Authentication API
Creation
Fetch
Deletion
Tenant Management API
Endpoint Index
Cloning
User Management API
Endpoint Index
Users
Roles
Permissions
User Role Assignments
User Tenant Assignments
Accounts API
Endpoint Index
Fetch
Account Creation
Updating
Validation
Contact Management
Quotes and Policies
Holds
Billing
Numbering
Contacts API
Endpoint Index
Quotes API
Endpoint Index
Main Flow
Fetch
Quote Creation
Update
Validation
Pricing
Underwriting
Acceptance
Issuance
Quote Copy and Group Assignment
Static Data
Documents
Billing
Contacts
Numbering
Atypical States and Operations
Quick Quotes API
Endpoint Index
Contacts
See Also
Policy Management API Index
Policies API
Endpoint Index
Fetch
Static Data
Snapshots
Billing Triggers
Billing
Numbering
Contacts
Policy Transactions API
Endpoint Index
Main Flow
Fetch
Transaction Creation
Updating
Validation
Pricing
Underwriting
Acceptance
Issuance
Documents
Transaction Details
Atypical States and Operations
Deprecated Items
Policy Terms API
Fetch
Term Summaries
Numbering
Renewal Management and Auto-Renewal API
Endpoint Index
Fetch
Create
Update
Plan Updates
See Also
Billing API Index
Main Index
Installments API
Installment Lattices API
See Also
Invoices API
Endpoint Index
Fetch
Invoice Documents
Invoice Preview
Numbering
Early Invoicing
Payments API
See Also
Disbursements API
Fetch
Lifecycle
Numbering
See Also
Credit Distribution API
Fetch
Creation and Update
Execution
Reversal
Reset and Discard
Invoices
Credits API
Flat Charges API
Create and Reverse
Fetch
Account Balances API
Financial Instruments and External Cash Transactions API
Financial Instruments
External Cash Transactions
Delinquency API
Delinquency Plan Assignment
Fetch
Delinquency Updates
Delinquency Events
See Also
Billing Holds API
Fetch
Creation and Update
Execution
Release, Reset, and Discard
See Also
Write-Offs API
Policy Service Endpoints
First Notice of Loss (“FNOL”) API
Endpoint Index
Fundamental Operations
Data Fetch
Numbering
Contacts
Loss Management
Events
Accounting API
Accounting Transactions
Accounting T-Accounts
Cash Accounts
Documents API
Fetch
Modification
Ad-hoc Rendering
See Also
Resources API Index
Resource Service API
Resource Groups
Resources
Document Resources API
Document Resources
Document Templates
Tables API
Data Tables
Usage
Configuration
Constraint Tables
Accounts
Quotes
Quick Quotes
Policy Transactions
Configuration
Secrets API
Data API Index
Aux Data API
Diary API
Fetch
Creation
Revisioning
Discard
See Also
Events API
Fetch
See Also
Diverted Events API
See Also
Search API
Data Search
See Also
Media API
Endpoint Index
Fetch
Management
Reporting API Index
Metrics API
Endpoint Index
Metrics Data Reponse Endpoints
Metrics CSV Download Endpoints
Metrics Request and Response Objects
See Also
Data Lake Delta Files API
Endpoint Index
Delta File Endpoints
Metrics Request and Response Objects
See Also
Configuration and Development API Index
Configuration Deployments API
Tenant Creation
Fetch
Redeployment
Validation
Utility
Configuration Entities
Developer API
Logging API
Jobs API
Endpoint Index
Documents Jobs
Job Retrigger
Installment Jobs
Invoice Jobs
Normal Invoicing
Early Invoicing
Delinquency Jobs
Identity Providers API
Webhooks API
See Also
Passwords API
Fetch
Update
See Also
Data Access Controls API
See Also
Migration API
Endpoint Index
Migration Management
Migration Information
Other Resources
Release Notes
April 23, 2025
Media Data
Search Updates
Coverage Terms Data Model Update
Configuration Redeployment Update
April 16, 2025
Policy Status
Bug Fixes
April 9, 2025
Search Update
More Contact Associations
Ad-Hoc Execution of Precommit Plugin
Full Stateless Pricing of Quote and Transactions
Bug Fixes
April 2, 2025
Notice: Classic Early Invoicing Endpoint Deprecation
March 26, 2025
New Features
Bug Fixes
March 19, 2025
March 12, 2025
New Feature: Data Lake Delta Files
New Data Lake Entities: Billing
Configuration Deployments API Update
Classic Endpoint List Behavior Deprecation
March 5, 2025
New Feature: First Notice of Loss
New Feature Guides
February 26, 2025
Bug Fix
February 19, 2025
Rating Plugin Interface Update
Invoices API Update
Resource Selection Update
Bug Fixes
February 12, 2025
Policy Transactions API Update
Jobs API Endpoint Deprecations
Bug Fix
Forthcoming Changes
February 5, 2025
Account Constraints
Documents API Update
Forthcoming Plugin Interface Changes
January 29, 2025
January 22, 2025
Forthcoming Plugin Interface Changes
List Endpoint Semantics Update
January 15, 2025
Underwriting Event Payload Updates
Other Changes
January 8, 2025
New Feature: Availability
New Feature: Contact Management
New Static Data Endpoints
Underwriting Update
December 18, 2024
User Management API Update
December 11, 2024
Migration API update
Identity Providers API update
December 4, 2024
New Feature: Data Lake (Beta)
New Feature: Value-Based Coverage Terms
Other Changes
Bug Fixes
November 20, 2024
New Feature: Early Invoicing
November 13, 2024
New Feature: Delinquency Events
November 6, 2024
Constraint Tables
Quote Events
Optional Properties
October 30, 2024
Constraints with Custom Data Types
Additional Changes to Paged List Fetch Semantics
Deployments
October 23, 2024
Data Access Controls
Webhooks Security Features
Yet More Changes to Paged List Fetch Semantics
Other Changes
October 16, 2024
Entity Numbering
More Changes to Paged List Fetch Semantics
Other Changes
October 9, 2024
New Feature Guides
Other Changes
October 2, 2024
September 25, 2024
New Getting Started Guide!
New Migration Feature Guide
Invoice Documents
Other Changes
September 18, 2024
External Documents
Other Changes
Older Changes
Deprecated API Items
Endpoints
POST /auth/identity
GET /billing/{tenantLocator}/jobs/earlyInvoicing/{jobLocator}
GET /billing/{tenantLocator}/jobs/earlyInvoicing/accounts/{locator}/list
GET /billing/{tenantLocator}/jobs/invoices/policies/{locator}/list
GET /billing/{tenantLocator}/jobs/invoices/quotes/{locator}/list
PATCH /policy/{tenantLocator}/policies/{locator}/billingTrigger
GET /policy/{tenantLocator}/policies/snapshot/list
GET /policy/{tenantLocator}/transactions/{locator}/affectedTransactions/list
GET /policy/{tenantLocator}/transactions/{locator}/segments/{segmentLocator}
GET /policy/{tenantLocator}/transactions/{locator}/segments/list
Entities
Account Response
Billing Plan Ref
Billing Preferences
Billing Trigger Update Request
Charge Ref
Configuration Ref
Document Job Info
Document Summary
Element Ref
Invoice Details Response
Params Change Instruction Create Request
Params Change Instruction Response
Policy Response
Policy Transaction Response
Product Ref
Quick Quote Price Response
Quote Create Request
Quote Update Request
Open API Definition File
Connected Core Docs
Socotra
Data Topic Index
Data Topic Index
Diaries
Media