Create Entity User

post

https://api.sb.spidrsrv.com/v1/entity/create

Use the /entity/create endpoint to create a new entity (business) user. This endpoint is specifically designed for onboarding business entities rather than individual users.

📘 Note: An entity user record is required before you can create a business account. The entity should pass all onboarding checks enforced by your program before creating an account.

Things to Note:

Entity users are identified by their EIN (Employer Identification Number) rather than SSN/ITIN.
Entity users have different required fields than individual users, including entityName and entityDetails.
Beneficial owners can be linked to the entity. Each beneficial owner must be an existing individual (non-anonymous) user, or an existing entity user when beneficialOwnerType is business.
When beneficial owners are added, they are automatically linked to the entity with a 'beneficial_owner' linkage type.
Beneficial owners are validated to ensure they belong to the same company as the entity being created.
A product can limit how many beneficial owners its entities have (for example exactly 1, or at most 5). When the number of beneficialOwners in the request is outside that limit, the create is refused with BENEFICIAL_OWNER_COUNT_RULE_NOT_SATISFIED (400), and the message gives the allowed range and the count.

Valid role values by beneficialOwnerType:

individual only: controlling_person, ceo, cfo, coo, president, vice_president, secretary, treasurer, director, managing_member, authorized_signer, sole_proprietor, grantor
business only: parent_company, holding_company
Either type: beneficial_owner, shareholder, member, general_partner, limited_partner, trustee, other

A role that is not allowed for the owner's beneficialOwnerType is rejected — controlling_person is the FinCEN CDD Rule control prong (a single individual with significant responsibility to control, manage, or direct the entity), so a business beneficial owner cannot hold it and belongs on the ownership side instead (for example beneficial_owner, parent_company or holding_company).

Body Params

POST /v1/entity/create Request body

sessionKey

string

The session key for the user. Created via Create ZTM Session and used for ZTM checks if your program is configured for ZTM.

bypassZtm

boolean

Indicates whether to bypass the ZTM checks if your program is configured for ZTM.

clientUserId

string

Unique ID that identifies the user in your system. This is your own ID for a given user if you also store/maintain user information.

customData

string

length ≤ 50

Optional custom data stored by Spidr for the user. The value can contain up to 50 characters.

idNumber

string

required

^[0-9]{9}$

The EIN (Employer Identification Number) for the entity

locale

string

enum

Defaults to en_US

The user's language and localization preference

Allowed:

entityName

string

required

length between 1 and 255

The legal name of the entity

string

required

length between 3 and 63

The user's email address

phoneNumber

string

The user's phone number. Prefer E.164 (+country code) for international numbers; national-format numbers are parsed with default region US.

address

object

required

initialProductId

string

required

Required. The product the user will be assigned to. Future accounts associated with a user can still be assigned different products upon account creation.

entityDetails

object

required

Additional details about the entity

idvTemplateId

string

Spidr KYB template ID that selects the business verification configuration to execute

businessEnrichmentId

string

enrichmentId of a business enrichment requested for this business on the same product before the application was submitted. The enrichment is linked to the new entity instead of ordering and billing another one; orderBusinessEnrichment and the KYB template's default are then ignored. It must not already be linked to an entity, must not have failed, and must have been placed: a pending enrichment that carries a BUSINESSPREFILL* errorCode was never placed and is refused. It never replaces idNumber: the full EIN is still required.

orderBusinessEnrichment

boolean

Order business enrichment for this business with the entity, when no businessEnrichmentId is supplied: once the entity is created, its entityName and address are submitted, the order is billed once, and the result arrives in the entity.businessEnrichmentUpdate webhook, typically about a minute later. The response's businessEnrichment block reports the order, normally pending. If the product already ordered enrichment for the same business (the same name and address) within its reuse window and that order is not linked to an entity, that order is linked to the new entity instead and nothing new is billed: the block carries its enrichmentId and current status, and an order that had already finished is not reported again in entity.businessEnrichmentUpdate. Overrides the default of the KYB template selected by idvTemplateId (bypassZtm false); false turns ordering off for this request. When this field is true, the product must be enabled for business enrichment with a provider account for this environment, and the entity's address must be in the US (enrichment covers US businesses), otherwise the request is refused before the entity is created with BUSINESS_PREFILL_SERVICE_NOT_ENABLED, BUSINESS_PREFILL_PROVIDER_NOT_CONFIGURED or BUSINESS_ENRICHMENT_COUNTRY_NOT_SUPPORTED. A template default that may not be ordered is skipped instead: the entity is created without an order. A create awaiting a manual decision places the order only on approval. Results are unverified commercial data: they never verify the business, change CIP, or feed KYB decisioning.

Responses

200POST /v1/entity/create Positive response

400POST /v1/entity/create Negative response