Skip to main content
Some connections need data from you before the provider can start: a lookup key that selects the person (a registration id, a phone number, a national id number), or the values a match connection should compare. You send these in the single userInput object of Create Verification.

Where the schema comes from

Every connection publishes its requirements as userInputJsonSchema, a JSON Schema (draft 2020-12) object, in Get Connections. The Console shows the same contract on a connection’s detail sheet under Claims → Request. Example: the schema of sk-mobile-id (read the actual fields from your connection):
A connection with no userInputJsonSchema needs no input. The user selects themselves in the provider’s own UI (most redirect-based eIDs work this way).

Field rules

Each entry in properties describes one field: The top-level required array lists the fields every request must send. A missing or empty ("") required field returns 400 VALIDATION_INVALID_PARAMETER naming it in details.parameter, for example userInput.registrationId. A required field sent as null also counts as not sent and returns 400 VALIDATION_MISSING_USER_DATA. A field that is not in required and has no enum or pattern is optional and accepted as sent. Keys the connection’s userInputJsonSchema does not list under properties are dropped before the provider is called. Only a connection without a userInputJsonSchema receives userInput unchanged. A value that fails the connection’s checks (for example a national ID number that doesn’t match its pattern) returns 422 VALIDATION_INVALID_USER_DATA. The provider can still reject a value that passes them, and how that’s reported depends on the connection.

Cross-field rules

Field rules describe one field at a time. A few connections also need a valid combination of fields. The schema states it with these keywords, checked when you create the verification: For example, Evrotrust identifies the person by an ID number with its country, an email, or a phone number. Send one of them:

Deprecated userInputSchema

userInputSchema is deprecated and will be removed on Mar 31, 2027. Use userInputJsonSchema instead.
Before userInputJsonSchema, Get Connections published the same contract as userInputSchema, a map of per-field rules. Get Connections still returns it next to userInputJsonSchema, unchanged, so an integration that reads it keeps working until the removal date. The response itself doesn’t mark the field as deprecated. userInputSchema differs from userInputJsonSchema in three ways:
  • It can’t express cross-field rules. For example, it lists every Evrotrust field as optional, although a request must send one of three field sets.
  • A connection added after userInputJsonSchema was introduced doesn’t include it.
  • Its rules are frozen, so they can fall behind userInputJsonSchema. For example, it still gives the ID number of ao-nin, ug-nin, and ke-alien-card a pattern that the server no longer checks, and it keeps hint values that have no matching description.
To migrate, read each rule from its place in userInputJsonSchema:

One field, two purposes

userInput is one flat map. Hopae decides what each value is for based on the connection’s credential.verificationModel:
  • disclosure: the values select the person or authorise the lookup. The provider then discloses the person’s attributes.
  • match: the same values are also the claims to compare. The provider answers whether they match, field by field, under match in the userinfo response. See Verification Model.
You never need to split the map into lookup keys and comparison values yourself.

Examples

Keys are the OIDC-normalized names listed in the schema (for example name, birthdate). They are echoed back unchanged in match.submitted_fields and match.details. The provenance block keeps the provider’s native names so the audit trail stays aligned with the source.