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
      • Invoice Fees
        • Example
      • 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
      • Document Consolidation
        • Example
      • Plugins
        • Policy Document Selection Plugin
        • Document Data Snapshot Plugin
        • Document Consolidation Snapshot Plugin
        • See Also
  • 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
        • Endpoint Index
        • 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
        • Add Invoice Fee to Policy or Quote
        • 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
    • May 7, 2025
      • New Feature: Invoice Fees
      • New Diary Associations
      • Update: Numbering
    • April 30, 2025
      • New Feature: Document Consolidation
      • Quick Quotes API Update
      • billingTrigger Deprecation
      • Deprecated Jobs API Endpoints Removed
      • Bug Fixes
    • 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
      • 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
  • Search

Search

Socotra’s search allows you to find the following entities quickly and easily:

  • Policies

  • Quotes

  • Accounts

  • Contacts

  • Diaries

  • First Notice of Loss (“FNOL”)

  • Payments

Overview

You can search against locators, static data, and data extensions of type string. For entities supporting numbering, you can also search by number. If there is a match with some degree of relevancy, the corresponding entity will be returned for that match. Results are ordered by relevancy score, from highest to lowest. Relevancy scores are boosted for exact matches on locators and static data, helping to ensure that such results emerge towards the top of the results.

Example

If you have an account configured with a data extension field lastName, and there is at least one account with last name “Swerski” in your set of accounts, a search query for Swerski will return at least one result: the account record for “Swerski”, with a high relative score.

Request

POST request body:

{
    "searchString":"Swerski"
}

Response

{
    "searchToken": "eyJzZWFyY2hSZXF1ZXN0Ijp7InNlYXJjaFN0cmluZyI6IlN3ZXJza2kifX0=",
    "offset": 0,
    "count": 10,
    "results": [
        {
            "score": 2.0,
            "searchEntityType": "account",
            "searchEntityLocator": "01JSH3DEPHHTRE6SQE8F9JH0J3",
            "searchSummary": {
                "account_number": "A223455",
                "data": {
                    "firstName": "Bill",
                    "lastName": "Swerski"
                },
                "name": "ConsumerAccount",
                "state": "validated"
            },
            "highlights": [
                "Score:2.0 ,Document: 01JSH3DEPHHTRE6SQE8F9JH0J3,Highlight: {entity.data.lastName=[<em>Swerski</em>]}"
            ]
        },
        {
            "score": 0.85714287,
            "searchEntityType": "account",
            "searchEntityLocator": "01JSH3E88RHZJTTVJNQX9XCAGK",
            "searchSummary": {
                "account_number": "B229455",
                "data": {
                    "firstName": "Bill",
                    "lastName": "Swersky"
                },
                "name": "ConsumerAccount",
                "state": "validated"
            },
            "highlights": [
                "Score:0.85714287 ,Document: 01JSH3E88RHZJTTVJNQX9XCAGK,Highlight: {entity.data.lastName=[<em>Swersky</em>]}"
            ]
        }
    ]
}

Note

A similar name, “Swersky”, appears in the results, but with lower relevance than the more exact match on “Swerski”. An exact match request with “Swerski” wrapped in (escaped) quotes would only return the “Swerski” account. Read on for details about search behavior and search string syntax.

Requests

Requests can be sent as a single searchString or as a searchTerm array. See the API reference for details.

Search String Syntax

A search request comprises search terms - an array of searchTerm items - and can be expressed as a searchString. searchString syntax allows you to express a complete query in a single string, such as one passed through a typical search form box.

A search string follows these rules:

  • A sequence one or more searchTerm strings, separated by whitespace.

  • Each searchTerm string has the following form:

    • Form: [+|-][fieldName:]string[*]

      • The fieldName slug determines whether the match should be against a specific field name or any field.

      • The fieldName can be qualified by the full path of the element to which it belongs, which allows for greater specificity in your query. For example, a top-level lastName data extension string on an account can be searched like this: +data.lastName:Swerski, while a firstName data extension on an exposure “insured” under some product can be searched as +insuredQuote.firstName:Veronica (for quotes) or +insuredPolicy.firstName:Veronica (for policies).

      • Term relevance scoring:

        • If the term is prefixed with a +, the term is required for search result relevance.

        • If the term is prefixed with a -, the term must be excluded for search result relevance.

        • Absence of + or - before a term is interpreted as a suggestion: the presence of the term increases the relevance score, but does not require that the term be present or absent from a match candidate.

    • The default match behavior is fuzzy.

      • Appending * to the term sets matching to startsWith.

      • Enclosing the term in double quotes sets matching to exact. Searches with spaces cannot be fuzzy searches.

Filtering

You may restrict results to a creation time range using the optional endCreationTime or startCreationTime SearchRequest parameters.

Responses

The SearchServiceResponse provides a list of SearchResultResponse results, along with properties to assist in paging through results.

You can fetch up to 100 results at a time, and use the count, offset, and searchToken values to control pagination. If no count is set for the initial search request, it will be set to 100. The searchToken should be used in subsequent GET requests to page through the results, with count serving as the number of results to be returned in the page and offset as the starting index (beginning at 0) in the result list. For example, if you perform a search with a total of 70 results, and want to page through 25 results at a time, you can do it with three requests, all setting count to 25:

  1. The initial query

  2. A second query, along with the searchToken and offset as 25

  3. A final query , along with the searchToken and offset as 50

You’ll know that you have exhausted the result set when the length of the result list is less than count. If there are no results beginning at some offset index, the service will return an empty result list. You can set the count to another value when fetching results; following the example above, if you decided you wanted all the results in a single response, just provide the searchToken with count at least 70. A provided count greater than 100 will be set to 100.

Relevance

The highlights and score properties provide additional context about the match. In highlights you will find one or more excerpts from text that matched the query, while score indicates the relative numerical value assigned for ranking. You’ll see very high score values for certain cases, such as exact matches on locator values.

Search Summary

The searchSummary object serves as a digest about the entity, reducing the need for subsequent data fetches from the API in order to understand which entity is being referred to, or to display the search result in an effective way. The contents of searchSummary depends on the result entity type:

  • Quotes and policies will have all static data fields in a static property.

  • Quotes will also have a state property.

  • All other searchable entities will include all string-type data extension field values in the data property.

“<entity>_number” will also appear as a search summary property if the entity supports numbering, and a number is assigned. The account results shown in this guide include account_number, for example.

Sample Responses

A SearchResultResponse for a “ConsumerAccount” account (search query was simply “Evans”):

{
    "score": 2.0,
    "searchEntityType": "account",
    "searchEntityLocator": "01JSH42HR5MYXAZQSCR13WNJ5P",
    "searchSummary": {
        "account_number": "C229458",
        "data": {
            "firstName": "Bill",
            "lastName": "Evans"
        },
        "name": "ConsumerAccount",
        "state": "validated"
    },
    "highlights": [
        "Score:2.0 ,Document: 01JSH42HR5MYXAZQSCR13WNJ5P,Highlight: {entity.data.lastName=[<em>Evans</em>]}"
    ]
}

A SearchResultResponse for a quote result when searched by locator – note the high relevancy score, since the search service boosts relevancy for exact matches on locators:

{
    "score": 101.0,
    "searchEntityType": "account",
    "searchEntityLocator": "01JSH42HR5MYXAZQSCR13WNJ5P",
    "searchSummary": {
        "account_number": "C229458",
        "data": {
            "firstName": "Bill",
            "lastName": "Evans"
        },
        "name": "ConsumerAccount",
        "state": "validated"
    },
    "highlights": [
        "Score:101.0 ,Document: 01JSH42HR5MYXAZQSCR13WNJ5P,Highlight: {entity.locator.keyword=[<em>01JSH42HR5MYXAZQSCR13WNJ5P</em>]}"
    ]
}

Configuration

Search is enabled by default, indexing both locators and data extension fields of type string. String field indexing includes data fields contained within Custom Data Types and in static data.

Locator indexing makes it possible to search for quotes, policies, and accounts by locator, along with elements by locator or static locator.

You may use the defaultSearchable and searchable configuration properties to more precisely control which string fields are indexed for search. defaultSearchable is available at the top level of the configuration, in addition to configuration for accounts, products, and elements. When defaultSearchable is true, all string fields at that level and below are indexed. When defaultSearchable is false, then a string field must have searchable set to true in order to be indexed for search. For a given field, the nearest defaultSearchable value when going up the configuration hierarchy applies.

Note

While Socotra allows you to create draft entities with fields not specified in the configuration, the search service will only index fields on draft entities that are actually present in the configuration.

See Also

  • Search API reference


© Copyright 2025, Socotra.

Built with Sphinx using a theme provided by Read the Docs
.