Add a Licensed Entity

Add a licensed entity

curl --request POST \
  --url https://public.api.live.turrisfi.com/v2/downstream/entities \
  --header 'Content-Type: application/json' \
  --data '
{
  "legalName": "Example Insurance Services of Pennsylvania, LLC",
  "branchName": "Philadelphia Branch",
  "npn": "1234567",
  "isNpnRequired": true,
  "ein": "12-3456789",
  "doingBusinessAs": "Example Branch",
  "incorporationStateCodes": [
    "PA"
  ],
  "website": "https://example-insurance.com",
  "phoneNumber": "+12155550100"
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    legalName: 'Example Insurance Services of Pennsylvania, LLC',
    branchName: 'Philadelphia Branch',
    npn: '1234567',
    isNpnRequired: true,
    ein: '12-3456789',
    doingBusinessAs: 'Example Branch',
    incorporationStateCodes: ['PA'],
    website: 'https://example-insurance.com',
    phoneNumber: '+12155550100'
  })
};

fetch('https://public.api.live.turrisfi.com/v2/downstream/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://public.api.live.turrisfi.com/v2/downstream/entities"

payload = {
    "legalName": "Example Insurance Services of Pennsylvania, LLC",
    "branchName": "Philadelphia Branch",
    "npn": "1234567",
    "isNpnRequired": True,
    "ein": "12-3456789",
    "doingBusinessAs": "Example Branch",
    "incorporationStateCodes": ["PA"],
    "website": "https://example-insurance.com",
    "phoneNumber": "+12155550100"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
    "branchName": "Philadelphia Branch",
    "isTopCompany": false,
    "incorporationStateCodes": [
      "PA"
    ],
    "legalName": "Example Insurance Services, LLC",
    "doingBusinessAs": "Example Insurance",
    "npn": "1234567",
    "ein": "12-3456789",
    "category": "agency",
    "parentId": "6610b3d2c2e0a51b8c0d1f01",
    "ultimateParentId": "6610b3d2c2e0a51b8c0d1f01",
    "dateIncorporated": "2015-06-01T00:00:00.000Z",
    "website": "https://example-insurance.com",
    "phoneNumber": "+12155550100",
    "legalAddress": {
      "country": "USA",
      "line1": "1200 Market St",
      "line2": "Suite 400",
      "city": "Philadelphia",
      "zip": "19107",
      "state": "PA"
    },
    "mailingAddress": {
      "country": "USA",
      "line1": "1200 Market St",
      "line2": "Suite 400",
      "city": "Philadelphia",
      "zip": "19107",
      "state": "PA"
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-02T08:12:44.000Z"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

POST

downstream

entities

Add a licensed entity

curl --request POST \
  --url https://public.api.live.turrisfi.com/v2/downstream/entities \
  --header 'Content-Type: application/json' \
  --data '
{
  "legalName": "Example Insurance Services of Pennsylvania, LLC",
  "branchName": "Philadelphia Branch",
  "npn": "1234567",
  "isNpnRequired": true,
  "ein": "12-3456789",
  "doingBusinessAs": "Example Branch",
  "incorporationStateCodes": [
    "PA"
  ],
  "website": "https://example-insurance.com",
  "phoneNumber": "+12155550100"
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    legalName: 'Example Insurance Services of Pennsylvania, LLC',
    branchName: 'Philadelphia Branch',
    npn: '1234567',
    isNpnRequired: true,
    ein: '12-3456789',
    doingBusinessAs: 'Example Branch',
    incorporationStateCodes: ['PA'],
    website: 'https://example-insurance.com',
    phoneNumber: '+12155550100'
  })
};

fetch('https://public.api.live.turrisfi.com/v2/downstream/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://public.api.live.turrisfi.com/v2/downstream/entities"

payload = {
    "legalName": "Example Insurance Services of Pennsylvania, LLC",
    "branchName": "Philadelphia Branch",
    "npn": "1234567",
    "isNpnRequired": True,
    "ein": "12-3456789",
    "doingBusinessAs": "Example Branch",
    "incorporationStateCodes": ["PA"],
    "website": "https://example-insurance.com",
    "phoneNumber": "+12155550100"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "downstreamEntityId": "6610b3d2c2e0a51b8c0d1f02",
    "branchName": "Philadelphia Branch",
    "isTopCompany": false,
    "incorporationStateCodes": [
      "PA"
    ],
    "legalName": "Example Insurance Services, LLC",
    "doingBusinessAs": "Example Insurance",
    "npn": "1234567",
    "ein": "12-3456789",
    "category": "agency",
    "parentId": "6610b3d2c2e0a51b8c0d1f01",
    "ultimateParentId": "6610b3d2c2e0a51b8c0d1f01",
    "dateIncorporated": "2015-06-01T00:00:00.000Z",
    "website": "https://example-insurance.com",
    "phoneNumber": "+12155550100",
    "legalAddress": {
      "country": "USA",
      "line1": "1200 Market St",
      "line2": "Suite 400",
      "city": "Philadelphia",
      "zip": "19107",
      "state": "PA"
    },
    "mailingAddress": {
      "country": "USA",
      "line1": "1200 Market St",
      "line2": "Suite 400",
      "city": "Philadelphia",
      "zip": "19107",
      "state": "PA"
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-02T08:12:44.000Z"
  },
  "requestId": "dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8",
  "timestamp": "2025-11-12T20:49:03.293Z"
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

{
  "statusCode": 123,
  "requestId": "<string>",
  "errorType": "validation_error",
  "errorMessage": [
    "<string>"
  ],
  "timestamp": "<string>",
  "details": {}
}

Creates a new legal entity as a branch of your top company, and provisions the organization behind it.

What you cannot set, and why

parentId

The tree is two levels — a top company and its direct branches — so the parent is always your own organization and there is nothing to choose. A branch cannot have a branch.

Product features and plan

Inherited from your top company. A branch is on its parent’s plan; choosing your own features through the API would be a self-service entitlement change.

Onboarding and customer flags

Platform state, not agency data.

Notes

branchName defaults to legalName when omitted. It cannot be stored empty.
NPN is not unique across your group: branches may legitimately share one. An NPN already held outside your organization is rejected with 409.
isNpnRequired: true without an npn is a 400. An entity with no NPN gets no compliance data subscription, so no licences or appointments will ever appear for it.

Send an Idempotency-Key header. See Idempotency.

Headers

idempotency-key

string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key

string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json

legalName

string

required

Registered legal name of the new entity.

Example:

"Example Insurance Services of Pennsylvania, LLC"

branchName

string

Name of this specific branch location. Defaults to the legal name when omitted — the field is required in storage and rejects an empty string, so there is no way to have no branch name.

Example:

"Philadelphia Branch"

npn

string

National Producer Number. Branches within one group may share an NPN, so this is not unique. An NPN already held outside your organization is rejected with 409.

Example:

"1234567"

isNpnRequired

boolean

Whether this entity is required to hold an NPN. When true, npn must be supplied. An entity with no NPN gets no NIPR subscription and therefore no licence or appointment data.

Example:

true

ein

string

Employer Identification Number

Example:

"12-3456789"

doingBusinessAs

string

Doing-business-as name

Example:

"Example Branch"

incorporationStateCodes

enum<string>[]

States and territories of incorporation

Available options:

AL,

AK,

AZ,

AR,

CA,

CO,

CT,

DE,

FL,

GA,

HI,

ID,

IL,

IN,

IA,

KS,

KY,

LA,

ME,

MD,

MA,

MI,

MN,

MS,

MO,

MT,

NE,

NV,

NH,

NJ,

NM,

NY,

NC,

ND,

OH,

OK,

OR,

PA,

RI,

SC,

SD,

TN,

TX,

UT,

VT,

VA,

WA,

WV,

WI,

WY,

GU,

PR,

VI,

DC

Example:

["PA"]

website

string

Website URL

Example:

"https://example-insurance.com"

phoneNumber

string

Primary phone number

Example:

"+12155550100"

Response

The entity that was created

data

object

required

Show child attributes

requestId

string

required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp

string

required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"

Start Here

Shared Endpoints

Licensed Entities

Producers

Contacts

Licenses

Actions Required

Licensing Overview

Appointments

License Requests

Compliance Configurations

Markets

Corporate Registrations

Documents

Surplus Lines

What you cannot set, and why

Notes

Headers

Body

Response

​What you cannot set, and why

​Notes

Headers

Body

Response

What you cannot set, and why

Notes