Create Account
Creates a new account in your user store. Invoke this method first when onboarding a new customer for your platform. Use [Account Update] when modifying an existing account.
Related guide: Account Creation and Updates
Example Request Body
- application/json
- Schema
{
"userReference": "string",
"customerInternalReference": "string",
"reportingCriteria": "string",
"callbackUrl": "https://mypreferredendpoint.com/callback",
"tokenLifetime": "15m",
"web": {
"successUrl": "string",
"errorUrl": "string",
"locale": "strin"
},
"workflowDefinition": {
"key": "10163",
"credentials": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"category": "ID",
"country": {
"predefinedType": "DEFINED",
"values": [
"AUT"
]
},
"type": {
"predefinedType": "DEFINED",
"values": [
"DRIVING_LICENSE"
]
}
}
],
"capabilities": {
"watchlistScreening": {},
"documentVerification": {
"enableExtraction": true
},
"ekycCheck": {
"searchType": "string"
},
"workflowDecision": {
"riskScoreRulesetId": "string",
"decisionLabelRulesetId": "string"
},
"ruleset": {}
}
},
"userConsent": {
"userIp": "string",
"userLocation": {
"country": "string",
"state": "string"
},
"consent": {
"obtained": "yes",
"obtainedAt": "2022-07-20T17:20:35.000Z"
}
},
"overrideSettings": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
accountRequest{
userReference
string
minLength: 1
maxLength: 100
Internal id used by the customer for the end user (must not contain PII).
See also Optional fields.
customerInternalReference*
string
minLength: 1
maxLength: 100
Internal reference used in the customer backend to identify the request (must not contain PII).
Must not contain any of the following characters: <>"/;`%{}|
reportingCriteria
string
minLength: 1
maxLength: 255
Additional information provided by the customer for searching and aggregation purposes.
See also Optional fields.
callbackUrl
string
minLength: 1
maxLength: 255
example: https://mypreferredendpoint.com/callback
URL to override the default callback url for this particular request.
See also Optional fields.
tokenLifetime
string
pattern: ^([+-]?\d+)([smhd]{1})$
example: 15m
Override the default token lifespan with another duration (example '1d' or '30m' or '600s'):
s - seconds
m - minutes
h - hours
d - days
See also Optional Fields.
web
webSettings{
Description: Web client settings.
successUrl
string
minLength: 1
maxLength: 255
Customer-served endpoint to handle successful acquisition scenarios during end user journey.
errorUrl
string
minLength: 1
maxLength: 255
Customer-served endpoint to handle error acquisition scenarios during end user journey.
locale
string
minLength: 1
maxLength: 5
Hyphenated combination of ISO 639-1:2002 alpha-2 language code plus ISO 3166-1 alpha-2 country. Example values:
'en'
'en-GB'
'de'
'es'
'zh-CN'
}
workflowDefinition*
workflowDefinition{
Description:
Definition of the specific documents necessary to execute for the particular capabilities on them.
key* string
minLength: 1
maxLength: 100
example: 10163
Key of the workflow definition.
credentials [
definition: An array of the <a href = "../../../References/Credential%20Reference.htm">credentials</a> required for the workflow.
credentialRequest{
Description: Optional. The credentials to require in workflow.
id string($uuid)
category*
credentialCategory
string
example: ID
Credential category. See the implementation guide for supported values. Example values:
'ID'
'FACEMAP'
'DOCUMENT'
'SELFIE'
country
credentialCountry{
Description: One or more country codes (ISO 3166-1 alpha-3) for the workflow definition.
predefinedType
predefinedType
string
default: DEFINED
Used to specify a set of values for the credentials that can be uploaded for the workflow:
- DEFINED: End user is not able to select other options even if they are defined in the KYX Portal.
values* [
example: List [ "AUT" ]
countryCodeISO3166alpha3string
(ISO 3166-1 alpha-3) country code.
Enum:
Array [ 252 ]
]
}
type
credentialType{
Description: Array of credential codes. You can find more information about possible values for particular credential categories in the implementation guide.
predefinedType predefinedTypestring
default: DEFINED
Used to specify a set of values for the credentials that can be uploaded for the workflow:
- DEFINED: End user is not able to select other options even if they are defined in the KYX Portal.
values* [
example: List [ "DRIVING_LICENSE" ]
string
]
}
}
]
capabilities
capabilityOptions{
Description: Options to provide capability-specific fields as part of the request.
watchlistScreening {
Description: Provide request options for the watchlistScreening capability.
}
documentVerification {
Description: Provide additional parameters for document verification.
enableExtraction
boolean
Used to disable Extraction in cases where a Document is uploaded to be stored but extracting the data is not required.
}
ekycCheck {
Description: Specify a 1x1 or 2x2 search.
searchType
string
Allowed values are one for 1x1 search, or two for 2x2 search.
}
workflowDecision {
Description: Specify a ruleset to override the default ruleset configured for your tenant for workflow decision
riskScoreRulesetId
string
Ruleset id.
decisionLabelRulesetId
string
Consult with Support before using.
}
ruleset {
Description:
Deprecated, use workflowDecision instead. Provide an array of ruleset IDs to override default workflow rulesets.
ids []
}
}
}
userConsent
userConsent{
Description: User consent information
userIp
string
maxLength: 100
The end user's IP address. Must be ipv4 or ipv6.
userLocation*
userLocation{
Description: The end user's location including country and state where applicable.
country
string($#/components/schemas/countryCodeISO3166alpha3)
The end user's country code in ISO-3166-alpha-3 format.
state
string
maxLength: 100
The end user's state of residence. State is mandatory when country is USA. For USA states, the format is alpha-2 code, for example: 'IL', 'CA'. For all other countries, state is optional.
}
consent
consent{
Description:
Status of user consent.
obtained string
example: yes
Values: 'yes' - user's consent was obtained. 'no' - user's consent was not obtained. 'na' - not applicable to the current request.
obtainedAt string($date-time)
example: 2022-07-20T17:20:35.000Z
The date and time in UTC when consent was obtained. Must be in the past relative to UTC time.
}
}
overrideSettings {
Description:
Allows overriding certain settings for the workflow execution.
< * >: string
}
}
Responses
201 - Created Account
- Example Value
- Schema
{
"timestamp": "2024-12-31T18:48:35.944Z",
"account": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"web": {
"href": "string",
"successUrl": "string",
"errorUrl": "string"
},
"sdk": {
"token": "string"
},
"workflowExecution": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"credentials": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"label": "string",
"category": "ID",
"country": {
"predefinedType": "DEFINED",
"values": [
"AUT"
]
},
"type": {
"predefinedType": "DEFINED",
"values": [
"DRIVING_LICENSE"
]
},
"allowedChannels": [
"string"
],
"api": {
"token": "string",
"parts": {
"front": "string",
"back": "string",
"face": "string",
"facemap": "string",
"prepared_data": "string",
"device_risk": "string",
"document": "string"
},
"workflowExecution": "string"
}
}
]
}
}
accountResponse{
Description:
The response contains data for use in subsequent transaction requests.
timestamp string($date-time)
Timestamp of response.
account {
id string($uuid)
}
web {
href string($uri)
successUrl string($uri)
errorUrl string($uri)
}
sdk {
token string
}
workflowExecution {
id string($uuid)
credentials [
Array of a href = "../../../References/Credential%20Reference.htm">credential response objects.
credentialResponse{
id string($uuid)
label string
A label provided by the workflow designer to distinguish credentials of the same category.
category credentialCategorystring
example: ID
Credential category. See the implementation guide for supported values. Example values:
'ID'
'FACEMAP'
'DOCUMENT'
'SELFIE'
country credentialCountry{
Description:
One or more country codes (ISO 3166-1 alpha-3) for the workflow definition.
predefinedType predefinedTypestring
default: DEFINED
Used to specify a set of values for the credentials that can be uploaded for the workflow:
- DEFINED: End user is not able to select other options even if they are defined in the KYX Portal.
values* [
example: List [ "AUT" ]
countryCodeISO3166alpha3string
(ISO 3166-1 alpha-3) country code.
Enum:
Array [ 252 ]
]
}
type credentialType{
Description:
Array of credential codes. You can find more information about possible values for particular credential categories in the implementation guide.
predefinedType predefinedTypestring
default: DEFINED
Used to specify a set of values for the credentials that can be uploaded for the workflow:
- DEFINED: End user is not able to select other options even if they are defined in the KYX Portal.
values* [
example: List [ "DRIVING_LICENSE" ]
string]
}
allowedChannels [
Channels that can be used to upload a particular credential (SDK, API, WEB).
string]
api apiActions{
Description:
Actions available for the API calls. Unavailable actions are omitted.
token string
JWT token used for all requests.
parts {
Description:
'Parts' refers to distinct types of identifying materials.
front string($uri)
href to manage FRONT part for the account credential.
back string($uri)
href to manage BACK part for the account credential.
face string($uri)
href to manage FACE part for the account credential.
facemap string($uri)
href to manage FACEMAP part for the account credential.
prepared_data string($uri)
href to manage PREPARED_DATA part for the account credential.
device_risk string($uri)
href to manage DEVICE_RISK part for the account credential
document string($uri)
href to manage document upload for the account credential.
}
workflowExecution string($uri)
href to manage the acquisition and workflow processing.
}
}]
}
}
401 - Unauthorized
- Example Value
- Schema
403 - Unauthorized
- Example Value
- Schema
404 - Unauthorized
- Example Value
- Schema