Pre-filling the KYC form

The hosted onboarding asks the end user seven KYC questions and then has them sign. If you already asked your client those questions in your own product, you can send the answers with the session. When everything that is needed is there, the end user skips the form and goes straight to reviewing and signing.

🚧
Only send answers that your client has given
The end user confirms the answers by signing the document that contains them. Do not guess, and do not use defaults of your own.

What you send

The answers go in the parameters of the session. kyc.questionsAndAnswers is a list of questions and answers. beneficialOwners says whether each beneficial owner is a politically exposed person (PEP).

You can send them when you create the session, or add them afterwards, see Adding the answers later.

{
  "session": {
    "sessionType": "ACCOUNT_ONBOARDING",
    "parameters": {
      "kyc": {
        "questionsAndAnswers": [
          {"q": "Vad ska finansierat kapital främst användas till?", "a": "Underlätta fakturahantering"},
          {"q": "Vilka belopp har fakturorna ni vill finansiera?", "a": "De är som minst 1 000 kr och som mest 50 000 kr"},
          {"q": "Hur ofta behöver ni finansiering?", "a": "Enstaka gång per månad"},
          {"q": "Hur många fakturor vill ni finansiera per månad?", "a": "0-5"},
          {"q": "Ange ungefärligt antal kunder kopplade till fakturor som ni vill finansiera kommande 12 månader.", "a": "25"},
          {"q": "Ange företagets beräknade omsättning för nästa år.", "a": "5 000 000 kr"},
          {"q": "Hur stor andel av er årsomsättning vill ni finansiera?", "a": "75 %"}
        ]
      },
      "beneficialOwners": [
        {"fullname": "Anna Andersson", "isPep": false}
      ]
    },
    "callbacks": {
      "onComplete": {"url": "https://example.com/onboarding/done"},
      "onCancel": {"url": "https://example.com/onboarding/cancelled"},
      "onError": {"url": "https://example.com/onboarding/failed"}
    }
  }
}

Questions must match the wording below exactly, including the final punctuation. The questions and the answers are in Swedish, because that is the language of the hosted form.

The questions and the answers

Question (`q`)	Answer (`a`)	Needed
`Vad ska finansierat kapital främst användas till?`	One of `Underlätta fakturahantering`, `Daglig verksamhet`, `Betala leverantörer`, `Investeringar`, `Betala löner`. Any other text is taken as free text.	Yes
`Vilka belopp har fakturorna ni vill finansiera?`	`De är som minst 1 000 kr och som mest 50 000 kr`, with your own amounts	Yes
`Hur ofta behöver ni finansiering?`	One of `Flera gånger i veckan`, `Flera gånger i månaden`, `Enstaka gång per månad`, `Kommer ej ha finansieringsbehov varje månad`	No. Without an answer it is `Enstaka gång per månad`
`Hur många fakturor vill ni finansiera per månad?`	One of `0-5`, `5-10`, `10-50`, `50+`, `Kommer ej ha finansieringsbehov varje månad`	No. Without an answer it is `0-5`
`Ange ungefärligt antal kunder kopplade till fakturor som ni vill finansiera kommande 12 månader.`	A number, such as `25`	Yes
`Ange företagets beräknade omsättning för nästa år.`	An amount in kronor, such as `5 000 000 kr`	Yes
`Hur stor andel av er årsomsättning vill ni finansiera?`	A whole percentage with a space before the sign, such as `75 %`. The form has `25 %`, `50 %`, `75 %` and `100 %`. Any other percentage is entered as a custom value.	Yes

Amounts can be written with or without spaces between the thousands (5000000 kr and 5 000 000 kr are the same).

📘
The two questions that are not needed still end up in the signed document
If you skip Hur ofta behöver ni finansiering? or Hur många fakturor vill ni finansiera per månad?, the form is filled in with the defaults in the table, and the end user signs them. Send your client's real answer if you know it.

Beneficial owners

Unless you say otherwise, the form lists the company's beneficial owners from company data, and the end user says for each of them whether they are a PEP. If you already know, send beneficialOwners:

"beneficialOwners": [
  {"fullname": "Anna Andersson", "isPep": false},
  {"fullname": "Bo Berg", "isPep": true}
]

Your list replaces the list from company data completely. Every owner must be in it, with the right fullname, or the document the end user signs will be wrong. An owner that you leave out is not shown. If you do not know the owners, leave beneficialOwners out.
Every entry needs fullname and isPep. isPep must be true or false, not text.
If an entry has no isPep, the end user is asked to confirm the owners themselves, and the form is shown.

When the form is skipped

The form is skipped when all of these are known:

the five questions marked "Yes",
isPep for every beneficial owner, and
a contact email address and, for onboarding, a bank account. Both come from the account, so create the account with a bank account and a contact address with an emailAddress.

Anything that is missing is asked in the hosted form, so a partial pre-fill is fine. The end user then only fills in the rest.

A few things to know:

An answer that does not match our wording is ignored without an error, and the field is empty in the form. The only exception is the first question, where any other answer is taken as free text. Always check a session in a real flow before you rely on the pre-fill.
A question that is sent twice uses the last answer.
The wording above is what the hosted form uses today. We tell you if it changes.

Adding the answers later

You do not have to know the answers when you create the session. Until the end user has opened the session url for the first time, you can add them with POST /sessions/{sessionId}:

curl -X POST "$BASE_URL/sessions/$SESSION_ID" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "parameters": {
        "kyc": {
          "questionsAndAnswers": [ ... ]
        },
        "beneficialOwners": [
          {"fullname": "Anna Andersson", "isPep": false}
        ]
      }
    }
  }'

Each parameter that you send replaces its earlier value as a whole, and parameters that you do not send are kept, such as locale. So always send the complete kyc (with every answer) and the complete beneficialOwners.
When the end user opens the url, the session is provisioned and its parameters can no longer be changed. After that you get 400 with the message Cannot update parameters on provisioned session.
To make sure that you do not overwrite a change, send the lastModifiedAt that you last read. You get 412 if the session has changed since.
A session that is completed, expired, failed or deleted cannot be updated.

KYC renewal

A session of type ACCOUNT_KYC_RENEWAL takes the same kyc and beneficialOwners parameters, with the same questions and answers, and the same rules. The bank account is not needed to skip the form, since the account already has one.

Trying it out

The sandbox uses a simulated onboarding, so do not rely on it to show how the real form is filled in. It accepts the answers, but that does not tell you that they match. Agree a test in the real flow with us before you go live, and check that the form behaves as you expect, in particular the beneficial owners.