User
This is a user of Swan - an actual person. Swan requires each user of our platform to have a unique and valid phone number. We made this choice because it allows us to offer a much simplified user experience.
Swan is login-less, so users don't have to remember anything; similar to Whatsapp. When it comes to sensitive transactions, our web Strong Customer Authentication gets users' consent and lets Swan verify their identity when necessary (like when they want to make a large transfer).
You must perform authentication when a user wishes to access their data (for example by logging into their web banking) or to make transactions through your service, via our API.
Logging into Swan is easy, but the very first time a user logs in differs from subsequent logins. Here's what the user experience is like after clicking the oAuth URL:
- 1.The user enters their phone number. This step can be bypassed if you already have this info. Learn more
- If onboarding via a mobile phone: a verification code will be sent by sms to confirm the phone number
- If onboarding via a desktop: a link will be sent by sms to confirm the phone number and subsequently open up the verification process on the smartphone
- 2.The user enters some personal data: first name, last name, and birthdate. This step can be bypassed if you already have this info. Learn more
- 3.The user selects a 6-digit passcode that will be used each time user consent is required. If available on the device, the user can also set up TouchID / FaceID for future consents.
- 4.The user performs identity verification: a combination of identity documentation and biometric face recognition. This step can be performed later.
- 5.Then the user can start using Swan!
- #nocode: they are redirected to your white-labeled web banking, and can start using our services.
- by API: they are redirected to the
redirectUrl
that you specified when you created the oAuth link.This will have thecode
for your customer. Learn more. Careful, if aredirectUrl
is specified, it must be declared in the list of possible Redirect URLs in the API Credentials tab on the dashboard.
Any subsequent logins will go even quicker: the user will simply confirm their phone number, enter their 6-digit passcode or use biometry, and then they're in!
If the user configured TouchID / FaceID, every time they log in or consent to a sensitive operation on the same device, it will be through their fingerprint or face scan. Here's the list of the supported browsers: https://caniuse.com/webauthn.
Only if they switch to another device will we ask them for their 6-digit passcode.
Sometimes, a user of Swan must prove their identity. For this purpose, Swan provides secure identity verification that uses streaming live-video and A.I. technology.
The identity verification can be performed 24/7 within a 10-minute timeframe, and includes the following validations:
- Is the ID document authentic?
- Is this person real?
- Does the face presented actually match the ID document?
During the verification process, the user has to login for security reasons.
Identity verification of a physical person is the first step in the verification of an account holder. Learn More
Identity verification can be removed for some B2B cases only with agreement by our compliance department. This is only possible for users that have non-sensitive access to an account. Learn more
Swan supports different levels of identification depending on the target use case. The same user can be verified with multiple identification levels.
- Expert
- Qualified Electronic Signature (QES)
- Prestataires de vérification d'identité à distance (PVID) (French IBANs only)

IdentificationLevels impact on identificationStatus State
Expert is the default identification level at Swan. It can be used to verify an account holder's legal representative as well as every account membership with sensitive access to an account. This requires a manual, asynchronous review by an expert.
To start the identification, the user must be redirected to an oauth2 authorization code process with the query parameter
identificationLevel=Expert
.QES confirms who created a document and that the document has not been altered since being signed, thus verifying the authenticity and integrity of the document. This electronic signature is compliant with EU Regulation No 910/2014 (eIDAS Regulation) for electronic transactions within Europe. Qualified Electronic Signatures can be considered as a digital equivalent to handwritten signatures.
Swan predominantly uses QES to verify individual account holders and requires a manual, asynchronous identity review by an expert before starting the signature.
- 1.To start the identification, the user must be redirected to an oauth2 authorization code process with the query parameter
identificationLevel=QES
- 2.After verification is done, the user's
identificationStatus
switches toReadyToSign
. - 3.Redirect the user to an OAuth2 authorization code process to sign our Terms and Conditions with the query parameter
identificationLevel=QES
.
PVID (in English, Remote Identity Verification Service Providers) only works for individual accounts with French IBANs.
PVID verifies a user's identity remotely using a cell phone to capture and verify identity documents and facial recognition. Any individual opening a French account can use PVID to complete identification if you configure it that way.
To start the identification, the user must be redirected to an OAuth2 authorization code process with the query parameter
identificationLevel=PVID
.Accepted identification levels vary by country based on local regulations. For each country and type of account, there is Swan's recommended level and, if applicable, other acceptable levels.
Refer to the following tables for recommendations for individual and company accounts. The first level listed is in bold with a checkmark (✓), indicating it is the level Swan recommends.
Account country | Individual accounts | Company accounts |
---|---|---|
🇫🇷 France | ✓ PVID
Expert + first transfer QES
(includes unregistered self-employed) | ✓ Expert
QES
PVID |
🇩🇪 Germany | ✓ QES + first transfer
(includes self-employed) | ✓ Expert
QES |
🇳🇱 Netherlands* | ✓ Expert
QES
PVID | ✓ Expert
QES
PVID |
🇪🇸 Spain | ✓ Expert
QES
PVID | ✓ Expert
QES
PVID |
∗ All self-employed account holders residing in the Netherlands should use
Expert
, regardless of account country.identificationStatus
is accessible in the user
query. It helps you follow the status of the last identification process. Use this to find out precisely what went wrong when a user was unable to be verified.You should ask the user to verify their identity only if the
identificationStatus
is not Processing
or ValidIdentity
.Once the identification status is
ValidIdentity
, unless the user reinitializes their smartphone browser, they will never again have to prove their identity with Swan for the given identification level.Each time the identification status changes to
ValidIdentity
or InsufficientDocumentQuality
or InvalidIdentity
or ReadyToSign
, the user receives a text message.With a project access token and the
users
query, you can retrieve the list of users who have signed in to your project at least one time. The users
query includes pagination, search, and filters.Include the
joinedAt
attribute to know when the user provided their first OAuth2 consent.There are two webhooks related to this query:
User.Joined
: webhook event when a user joins a projectUser.Updated
: webhook event when there is an update to the user
Use these webhooks to receive notifications about your user's progress during the identity verification process, including updates such as a changed phone number.
User.Joined
and User.Updated
are different from other Swan webhooks: you cannot query by the userId
. If you want information about a userId, act as or "impersonate" the user with a project access token instead.Request
Response
Sample request with the
users
query to retrieve ......1
query MyQuery {
2
users {
3
edges {
4
node {
5
id
6
joinedAt
7
lastName
8
mobilePhoneNumber
9
nationalityCCA3
10
preferredNotificationChannel
11
updatedAt
12
identificationStatus
13
idVerified
14
identificationLevels {
15
expert
16
QES
17
PVID
18
}
19
firstName
20
createdAt
21
birthDate
22
authenticators {
23
acceptLanguage
24
brand
25
type
26
userAgent
27
os
28
model
29
}
30
allFirstNames
31
}
32
}
33
}
34
}
35
1
{
2
"data": {
3
"users": {
4
"edges": [
5
{
6
"node": {
7
"id": "8e64106e-406a-4c74-83f9-4a5b01bb1608",
8
"joinedAt": "2023-04-25T13:39:39.171Z",
9
"lastName": "Ngoma",
10
"mobilePhoneNumber": "+33123456789",
11
"nationalityCCA3": "FRA",
12
"preferredNotificationChannel": null,
13
"updatedAt": "2023-04-25T13:38:38.454Z",
14
"identificationStatus": "ValidIdentity",
15
"idVerified": false,
16
"identificationLevels": {
17
"expert": false,
18
"QES": false,
19
"PVID": false
20
},
21
"firstName": "Malika",
22
"createdAt": "2023-04-25T13:38:38.454Z",
23
"birthDate": "1111-11-11",
24
"authenticators": [
25
{
26
"acceptLanguage": null,
27
"brand": null,
28
"type": "SwanWeb",
29
"userAgent": "Mozilla/5.0 (Linux; Android 13; NE2213) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
30
"os": null,
31
"model": null
32
}
33
],
34
"allFirstNames": null
35
}
36
},
37
{
38
"node": {
39
"id": "89bba9e2-a09d-4512-ac63-e1894b31a278",
40
"joinedAt": "2023-04-25T12:38:34.445Z",
41
"lastName": "Janssen",
42
"mobilePhoneNumber": "+33123456789",
43
"nationalityCCA3": "NLD",
44
"preferredNotificationChannel": null,
45
"updatedAt": "2023-04-25T12:37:36.294Z",
46
"identificationStatus": "ValidIdentity",
47
"idVerified": true,
48
"identificationLevels": {
49
"expert": true,
50
"QES": false,
51
"PVID": false
52
},
53
"firstName": "Catharijne",
54
"createdAt": "2023-04-25T12:37:36.294Z",
55
"birthDate": "1111-11-11",
56
"authenticators": [
57
{
58
"acceptLanguage": null,
59
"brand": null,
60
"type": "SwanWeb",
61
"userAgent": "Mozilla/5.0 (Linux; Android 13; NE2213) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
62
"os": null,
63
"model": null
64
}
65
],
66
"allFirstNames": null
67
}
68
},
69
{
70
"node": {
71
"id": "fa7290b0-51ca-4ca4-a04c-057713e6eaf7",
72
"joinedAt": "2023-04-24T13:42:30.302Z",
73
"lastName": "Moreno",
74
"mobilePhoneNumber": "+33678458765",
75
"nationalityCCA3": "ESP",
76
"preferredNotificationChannel": null,
77
"updatedAt": "2023-04-20T07:53:06.965Z",
78
"identificationStatus": "ValidIdentity",
79
"idVerified": false,
80
"identificationLevels": {
81
"expert": false,
82
"QES": false,
83
"PVID": false
84
},
85
"firstName": "Alberto",
86
"createdAt": "2023-04-20T07:53:06.965Z",
87
"birthDate": "1996-12-20",
88
"authenticators": [
89
{
90
"acceptLanguage": null,
91
"brand": null,
92
"type": "SwanWeb",
93
"userAgent": "Mozilla/5.0 (Linux; Android 13; NE2213) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
94
"os": null,
95
"model": null
96
}
97
],
98
"allFirstNames": null
99
}
100
},
101
"allFirstNames": []
102
}
103
}
104
]
105
}
106
}
107
}
To make your integration with Swan as seamless as possible, we allow you to create as many Sandbox users as you want from Swan. Sandbox users make it possible to simulate the different processes you may encounter with your real users, once you go live. You can simulate different onboarding scenarios and processes, or practice managing the user rights of your accounts.
When you add members to your project on the dashboard, they have access to the menu Sandbox Users. By default, you have a first Sandbox user: Jane Doe. It is easy to add, modify, or delete Sandbox users from this tab.
Here are the settings you can modify for each Sandbox user:
- First Name
- Last Name
- Birthdate
- Nationality
- Identification status: lets you simulate all the states during the identity verification process. Learn more
- If one of the identification levels is selected, the sandbox is considered verified regardless of the identification status
- Auto consent: saves you considerable time during the development phase, by automatically allowing consent, removing the need to repeatedly get consent.

When you are playing in the Sandbox environment - using Swan API, simulating the onboarding of a new account holder, accessing web banking - the user being employed is the one selected in the dashboard. To change users, just select a different one.
Last modified 15d ago