# Regions



Overview [#overview]

In Socotra Insurance Suite, regions are used to lend organizational context to the work being done. While generally used to represent a geographic region or state (e.g. `"North East"`, `"South West"`, `"SW"`, `"CA"`, `"TX"`, `"VIC"`, `"NSW"` etc), implementers may define whatever collection of regions makes sense for their business use cases.

Regions are defined as a list of strings in configuration, and on the operational side can be assigned to draft quotes. The region value on a quote is automatically copied over to the policy upon issuance. Adding regions to the configuration is optional, as is utilizing them on any given quote or policy.

Once set on a quote and validated, the `region` property is fixed for the life of the policy. The property will appear at the top level of a <ApiLink name="QuoteResponse">quote</ApiLink> and <ApiLink name="PolicyResponse">policy</ApiLink>.

Use Cases [#use-cases]

There are currently three primary use cases for the `region` property, with more to follow.

1. **Reporting:** The `region` property is replicated into [Data Lake](/features/reporting/datalake) and can be leveraged to bring the intended context through to reporting.
2. **Data Access Control:** The `region` property can be leveraged as one of several values upon which implementers can control which users can access which quotes, policies, or their related entities via the [Data Access Controls](/features/security/data-access-controls) feature.
3. **Work Management:** In a work management context, regions will be used primarily as a container for users, groups, and business practice settings. An activity (a specific task or item of work to be done) can be assigned to someone in a given region. More details to follow as our forthcoming Work Management capabilities reach general availability.

Configuration [#configuration]

Like many other configurable entities, regions are defined in <ApiLink name="ConfigurationRef">configuration</ApiLink> as a map of <ApiLink name="RegionRef" />.

```javascript
{
  // other config entities
  "regions":{
      "NW": {
          "displayName" : "North West"
      },
      "NE": {
          "displayName" : "North East"
      }
  }
}
```

Quote and Policy Regions [#quote-and-policy-regions]

Assuming there have been regions configured for the tenant, a quote can be assigned a region while in draft state via a <ApiLink name="createQuote">create</ApiLink> or <ApiLink name="updateQuote">update</ApiLink> request.

<ApiEndpoint name="createQuote" title="Create a Quote" />

<ApiSchema name="QuoteCreateRequest" />

If set, the `region` property will appear in the top level of the response when fetching a <ApiLink name="fetchQuote">quote</ApiLink> or <ApiLink name="fetchPolicy">policy</ApiLink>.

<ApiEndpoint name="fetchQuote" title="Fetch a Quote" />

<ApiSchema name="QuoteResponse" />

<ApiEndpoint name="fetchPolicy" title="Fetch a Policy" />

<ApiSchema name="PolicyResponse" />


## API Reference

POST /policy/{tenantLocator}/quotes — createQuote
Tags: quotes-controller
Permissions: write, create
Parameters:
  tenantLocator (uuid, path, required)
Request body (QuoteCreateRequest):
Responses:
  200 QuoteResponse — OK

GET /policy/{tenantLocator}/quotes/{locator} — fetchQuote
Tags: quotes-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 QuoteResponse — OK

GET /policy/{tenantLocator}/policies/{locator} — fetchPolicy
Tags: policies-controller
Permissions: read
Parameters:
  tenantLocator (uuid, path, required)
  locator (ulid, path, required)
Responses:
  200 PolicyResponse — OK

QuoteCreateRequest
Properties:
  productName (string, required)
  accountLocator (ulid, required)
  startTime (datetime, required)
  endTime (datetime)
  expirationTime (datetime)
  currency (string)
  timezone (string)
  jurisdiction (string)
  coverageTerms (map<string, object>)
  data (map<string, object>, required)
  elements (ElementCreateRequest[])
  durationBasis (Enum years | months | weeks | days | hours)
  preferences (PreferencesResponse)
  delinquencyPlanName (string)
  autoRenewalPlanName (string)
  billingLevel (Enum account | inherit | policy)
  region (string)
  quoteGroupLocator (ulid)
  static (map<string, object>)
  contacts (ContactRoles[], required)
  invoiceFeeAmount (number, required)
  termDuration (integer)
  producerCode (string)

QuoteResponse
Properties:
  locator (ulid, required)
  quoteState (Enum draft | validated | earlyUnderwritten | priced | underwritten | accepted | issued | underwrittenBlocked | declined | rejected | refused | discarded, required)
  productName (string, required)
  accountLocator (ulid, required)
  startTime (datetime)
  endTime (datetime)
  timezone (string)
  currency (string)
  underwritingStatus (string)
  expirationTime (datetime)
  element (ElementResponse, required) — The root element in the hierarchy
  preferences (PreferencesResponse) — Plan selections and setting overrides
  policyLocator (ulid)
  delinquencyPlanName (string)
  durationBasis (Enum years | months | weeks | days | hours)
  groupLocator (ulid)
  autoRenewalPlanName (string)
  billingLevel (Enum account | inherit | policy, required)
  region (string)
  quoteNumber (string)
  duration (number) — The duration of the prospective policy in units of durationBasis
  acceptedTime (datetime)
  issuedTime (datetime)
  validationResult (ValidationResult)
  quickQuoteLocator (ulid)
  contacts (ContactRoles[], required)
  anonymizedAt (datetime)
  invoiceFeeAmount (number)
  createdBy (uuid)
  createdAt (datetime)
  jurisdiction (string)
  producerCode (string)
  reservedPolicyNumber (string)
  static (map<string, object>)
  policyNumber (string)

PolicyResponse
Properties:
  locator (ulid, required)
  accountLocator (ulid, required)
  branchHeadTransactionLocators (ulid[]) — The locators of all the top-level transactions on the policy, one per branch
  issuedTransactionLocator (ulid, required) — The locator of the latest issued transaction for the policy.
  productName (string, required)
  timezone (string, required)
  currency (string, required)
  durationBasis (Enum years | months | weeks | days | hours, required)
  createdAt (datetime, required)
  createdBy (uuid, required)
  delinquencyPlanName (string)
  autoRenewalPlanName (string)
  startTime (datetime, required) — The start time, based on issued transactions only
  endTime (datetime, required) — The end time based on issued transactions only.
  latestTermLocator (ulid, required)
  billingLevel (Enum account | inherit | policy, required)
  region (string)
  policyNumber (string)
  latestSegmentLocator (ulid, required) — The last segment on the policy, based on issued transactions only
  contacts (ContactRoles[], required)
  statuses (Enum[], required)
  invoiceFeeAmount (number)
  anonymizedAt (datetime)
  coverageEndTime (datetime)
  moratoriumElections (map<string, string>, required)
  jurisdiction (string)
  producerCode (string)
  producerCodeOfRecord (string)
  static (map<string, object>, required)
  validationResult (ValidationResult)