Built-in schemas

Built-in schemas

The backend ships with 33 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, and Organization API corrections, which are validated against the copy’s own schema. 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" }
}

No top-level field is required by any schema: a document may be created empty and filled over versions. Fields typed date, country, currency, email and uri are validated semantically — see custom field formats.

Scope grouping

The catalog groups into three scopes:

Scope Count Meaning
PERSON 22 Personal data shapes
ORGANIZATION 10 Corporate / legal-entity data shapes
SERVICE 1 Platform-generated shapes (UBO)

A manifest slot about the account holder or a family member takes PERSON schemas; a slot about a company subject takes ORGANIZATION schemas (and, as the one SERVICE exception, UBOStructure).

One-per-vault schemas

Twelve schemas are singletons: every vault of their kind is minted with one document of each, the platform protects it from deletion (403 delete_refused), and a second instance is never created. Fill the value rather than offering a choice — see the recipe.

Vault kind Singletons
Person PersonFullName, PersonGender, PersonBirthDetails, PersonNationality, PersonTaxStatus, PersonFinancialProfile
Legal entity LegalEntity, LegalEntityOperations, LegalEntityTaxStatus, LegalEntityControllers, LegalEntityRepresentatives, UBOStructure

Every other schema is multi-instance: several addresses, several bank accounts, one PersonFlight per leg.

PERSON (22)

PersonFullName

Full name. Singleton.

Field Type Notes
firstName string Given name
middleName string Middle name
lastName string Family name
preferredName string The name the person prefers to be called

PersonGender

Singleton.

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

PersonBirthDetails

Singleton.

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

PersonNationality

Singleton.

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

PersonCivicRegistration

Registration in a national population register.

Field Type Notes
country string (country) Country of the register
civicNumber string National personal public number (BSN, NINo, SSN, …); where it doubles as the tax ID it is recorded in PersonTaxStatus too
municipality string Municipality of registration
registrationDate string (date)

PersonIdentityDocument

A government-issued identity document as typed data.

Field Type Notes
documentType string Enum: Passport, National ID Card, Driver License, ID Card, Residence Permit, Travel Document, Visitor Visa, Other
documentNumber string
issuingCountry string (country)
issueDate string (date)
expiryDate string (date)
issuingAuthority string

PersonImmigrationStatus

Field Type Notes
country string (country) Country of the immigration case
permitType string e.g. “Highly Skilled Migrant”, “EU Blue Card”
foreignerNumber string Foreign-national registration number (e.g. V-nummer)
caseReference string Immigration authority file reference
sponsorName string Sponsoring organization
sponsorReference string Recognised sponsor registration number
validFrom string (date)
validUntil string (date)

PersonMarriage

Marriage or registered partnership.

Field Type Notes
partnershipType string Enum: Marriage, Registered partnership, Civil union, Other
partnerFullName string
date string (date) Date of marriage or registration
country string (country) Where the union was concluded
place string City or municipality on the certificate
registryReference string Act or certificate number
endDate string (date) Omit if ongoing
endReason string Enum: Divorced, Widowed, Annulled

PersonEducation

Field Type Notes
institutionName string
level string Enum: Primary school, Secondary school, Vocational, Bachelor, Master, Doctorate, Other
qualificationName string e.g. “MSc Computer Science”
fieldOfStudy string
startDate string (date)
endDate string (date) Omit if ongoing
country string (country) Country of the institution

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
grossSalary number Per salaryPeriod
salaryCurrency string (currency) ISO 4217
salaryPeriod string Enum: Hourly, Weekly, Monthly, Annual
contractType string Enum: Permanent, Fixed-term, Temporary agency, Freelance, Secondment, Other
hoursPerWeek number

PersonTaxStatus

Singleton.

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

PersonTaxScheme

A granted tax scheme or ruling.

Field Type Notes
country string (country) Country that granted the scheme
scheme string e.g. “30% facility”
referenceNumber string Decision reference number
validFrom string (date)
validUntil string (date)

PersonFinancialProfile

Singleton.

Field Type Notes
sourceOfWealth string Origin of wealth
sourceOfFunds string Origin of funds
grossAnnualIncome number
grossAnnualIncomeCurrency string (currency) ISO 4217

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)

PersonPhone

Field Type Notes
telephone string Phone number

PersonWebsite

Field Type
website string (uri)

PersonInsurancePolicy

Field Type Notes
insuranceType string Enum: Health, Liability, Home contents, Building, Travel, Vehicle, Other
providerName string
policyNumber string
coverageStartDate string (date)
coverageEndDate string (date) Omit if ongoing
country string (country) Country of the policy

PersonUtilityAccount

Field Type Notes
serviceType string Enum: Electricity, Gas, Water, Internet, Mobile, TV, Other
providerName string
accountReference string Customer or account number
startDate string (date)

PersonFlight

One document per leg; connections share a booking reference.

Field Type Notes
direction string Enum: Inbound, Outbound (relative to the relocation destination)
date string (date)
flightNumber string e.g. “KL 1602”
airline string Operating airline
bookingReference string Reservation code (PNR)
departureCity string
departureCountry string (country)
arrivalCity string
arrivalCountry string (country)

PersonPet

Field Type Notes
name string
animalType string e.g. dog, cat
breed string
sex string Enum: Male, Female, Unknown
dateOfBirth string (date)
size string Size, weight or dimensions as carriers ask for them
microchipNumbers array of string
notes string

ORGANIZATION (10)

LegalEntity

Core identification information for a legal entity. Singleton.

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

Singleton.

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

LegalEntityOperations

Singleton.

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

LegalEntityControllers

Singleton.

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

LegalEntityRepresentatives

Singleton.

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

SERVICE (1)

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

UBOStructure

Ultimate Beneficial Owner tree of a legal entity. Singleton, and the one service schema a manifest may ask about a company subject. 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)
self boolean This person is the representative completing the request
identification object { "mode": "self" | "delegated" } — how the owner’s identification is collected
proofOfAddress object { "mode": "self" | "delegated" } — how the owner’s proof of address is collected

mode: "self" means the company uploads the evidence; "delegated" means the owner is invited to upload it themselves.

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.