Built-in schemas

Built-in schemas

The backend ships with 24 built-in JSON schemas that document data payloads are validated against — including Partner API create and write payloads, where a schema slot’s target names one of these schemas. They cover personal, corporate, and platform-service data shapes.

Canonical schemaRef format

Every built-in schema has a canonical reference URL:

https://schema.identa.io/core/{SchemaName}.json

The backend resolves this URL to the embedded JSON Schema at write time and validates data against it. Slot targets accept either spelling — the bare schema name or the canonical URL.

Example:

{
  "schemaRef": "https://schema.identa.io/core/PersonFullName.json",
  "name": "My name",
  "data": { "firstName": "Alice", "lastName": "Liddell" }
}

Scope grouping

The catalog groups into three scopes:

Scope Count Meaning
PERSON 12 Personal data shapes
ORGANIZATION 10 Corporate / legal-entity data shapes
SERVICE 2 Platform-generated shapes (ID scan, UBO)

PERSON (12)

PersonFullName

First / middle / last name.

Field Type Notes
firstName string Given name
middleName string Middle name
lastName string Family name

PersonGender

Field Type Notes
gender string Enum: Male, Female, Other

PersonBirthDetails

Field Type Notes
dateOfBirth string (date) ISO 8601
countryOfBirth string (country) ISO 3166-1 alpha-2
cityOfBirth string Free text

PersonNationality

Field Type Notes
nationality array of string (country) Multiple allowed (dual/multiple)

PersonJob

Field Type Notes
jobTitle string e.g. “Financial Manager”
employerName string
employmentType string e.g. “Full-time”, “Part-time”
employmentStartDate string (date)
employmentEndDate string (date) Omit if currently employed

PersonTaxStatus

Field Type Notes
taxID string TIN / CIF / NIF etc.
taxResidenceCountry string (country)
additionalTaxResidenceCountry array of string (country) Secondary residencies

PersonAddress

Field Type Notes
streetAddress string
streetAddressLine2 string Apt / suite / unit
city string
postalCode string
addressRegion string State / province
addressCountry string (country)

PersonBankAccount

Field Type Notes
swiftBic string SWIFT or BIC code
accountNumber string IBAN or local
bankName string
accountHolderName string
currency string (currency) ISO 4217

PersonEmail

Field Type Notes
email string (email)

PersonFinancialProfile

Field Type Notes
sourceOfWealth string Origin of wealth
sourceOfFunds string Origin of funds
grossAnnualIncome number

PersonPhone

Field Type Notes
telephone string Phone number

PersonWebsite

Field Type
website string (uri)

ORGANIZATION (10)

LegalEntity

Core identification information for a legal entity.

Field Type Notes
legalName string Registered company name
registrationNumber string
registrationCountry string (country)
tradingName array of string Trading names if different from legal name
registrationDate string (date)
legalForm string
legalEntityStatus string Enum: Active, NonActive, Pending, Other
website string (uri)

LegalEntityAddress

Same shape as PersonAddress.

LegalEntityBankAccount

Same shape as PersonBankAccount.

LegalEntityEmail

Same shape as PersonEmail.

LegalEntityPhone

Same shape as PersonPhone.

LegalEntityWebsite

Same shape as PersonWebsite.

LegalEntityTaxStatus

Field Type Notes
taxID string TIN / CIF / NIF etc.
vatID array of string VAT numbers
taxResidenceCountry string (country)
additionalTaxResidenceCountry array of string (country)

LegalEntityOperations

Field Type Notes
industry string Primary sector
businessDescription string
mainProducts string Main products / services
numberOfEmployees number
operatingCountries array of string (country)

LegalEntityControllers

Field Type Notes
controllers array of object Each item: { firstName, lastName }

LegalEntityRepresentatives

Field Type Notes
representatives array of object Each item: { firstName, lastName }

SERVICE (2)

Service schemas are produced by platform components rather than user input — they’re typically written automatically and read by clients.

IDDocumentScan

Populated from a FaceTech ID-document scan. Fields are prefixed localized… when the document’s local-language rendering is preserved verbatim.

Field Type Notes
firstName string As shown on the document
middleName string
lastName string
localizedDateOfBirth string Document’s own date format
localizedPlaceOfBirth string Local language
localizedNationality string Local language
localizedSex string Local language
localizedCountry string Issuing country, local language
idNumber string Primary identifier / passport number
localizedDateOfIssue string Local format
localizedDateOfExpiration string Local format
localizedIssuingAuthority string Local language
localizedAddressLine1 string Local language
localizedAddressLine2 string Local language

UBOStructure

Ultimate Beneficial Owner tree. owners is a recursive list of PersonUBO or OrganizationUBO entries discriminated by ownerType ("person" or "organization").

PersonUBO entry

Field Type Notes
id string UUID
ownerType string Fixed "person"
percentageOfShare number 0–100
firstName string
lastName string
telephone string
email string (email)

OrganizationUBO entry

Field Type Notes
id string UUID
ownerType string Fixed "organization"
percentageOfShare number 0–100
creditSafeConnectId string Auto-filled from CreditSafe search
registrationNumber string
legalName string
country string (country)
email string (email)
children array of UBOEntry Owners of this organization (recursive)

Custom field formats

Several schemas use non-standard JSON Schema format values the backend validates semantically:

format Meaning
country ISO 3166-1 alpha-2 (2-letter code)
currency ISO 4217
email RFC 5322 email
date ISO 8601 date
uri Valid URI

Clients that use a generic JSON Schema validator can treat country / currency as free strings; the authoritative verdict is the server’s validation at write time.