API ExplorerAPI ReferenceRoadmapStatus Page
Search
⌃K
Links

User

Definition

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).

Authentication

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.
Swan's API for user authentication is based on the technology oAuth2 OpenIDConnect. Learn More​
A connected user's data is available at the root of the user query.

User login process

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. 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. 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. 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. 4.
    The user performs identity verification: a combination of identity documentation and biometric face recognition. This step can be performed later.
  5. 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 the code for your customer. Learn more. Careful, if a redirectUrl 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.

Identity Verification

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​

Identification Level

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

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.

Qualified Electronic Signature (QES)

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. 1.
    To start the identification, the user must be redirected to an oauth2 authorization code process with the query parameter identificationLevel=QES
  2. 2.
    After verification is done, the user's identificationStatus switches to ReadyToSign.
  3. 3.
    Redirect the user to an OAuth2 authorization code process to sign our Terms and Conditions with the query parameter identificationLevel=QES.

Prestataires de vérification d'identité à distance (PVID)

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.

Identification level recommendations

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.

Identification Status

identificationStatus is accessible in the userquery. 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.

Users query

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 project
  • User.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
}

Sandbox Users

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​
  • Identification levels: lets you simulate all the levels. 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.
Concepts - Previous
Overview
Next - Concepts
Projects
Last modified 15d ago