Users
A user represents a company or a person sharing access to their data. Each user may have multiple data connections to different providers.
Usually each user represents one of your customers.
There are two types of user:
- Legal user: represents a company or professional activity
- Natural user: represents an individual person
Create a legal user
Creating a legal user is done through the endpoint POST /api/v6/users/legal.
The two main fields are name, and siren. The name is mandatory, and is meant for you to identify your users.
The siren is the registration number of your user's enterprise. In France, that registration number
is the SIREN code, but that changes depending on the country for which you
consider your user.
In the rare cases where your user does not yet have a registration number, you may create your
user on the Qard API without one. In such a situation you may still add other data about your user,
such as the postal code of your user, their country and their activity code.
The users you create do not have to be unique, as they are given a unique id
generated upon creation. You should store this id in your system to interact
with the user later on.
| Field | Type | Description |
|---|---|---|
| name | string | Mandatory, used for you to identify your user |
| siren | string | Optional, registration code of your user's company. Must be a SIREN code over 9 digits if not left out and country is France |
| postal_code | string | Optional, postal code of the user's city |
| country | string | Optional, 2-letter code of the user's country. Defaults to "FR" (France) if left blank, or left out. |
| ape_code | string | Optional, Activity code of the user |
| group | string | Optional, the group name is meant for you to segment your users. Defaults to "default" if left out. |
| return_url | string | Optional, the url on your system where the user is redirected when the authorizations process is finished |
Create a natural user
Creating a natural user is done through the endpoint POST /api/v6/users/natural.
A natural user is identified by their name and birth date.
The users you create do not have to be unique, as they are given a unique id
generated upon creation. You should store this id in your system to interact
with the user later on.
| Field | Type | Description |
|---|---|---|
| firstname | string | Mandatory, first name of you user |
| lastname | string | Mandatory, original surname of you user (usually their birth surname). |
| birth_date | date | Birth date of the user |
| group | string | Optional, the group name is meant for you to segment your users. Defaults to "default" if left out. |
| return_url | string | Optional, the url on your system where the user is redirected when the authorizations process is finished |
Create a user
To create a legal user use POST /api/v6/users/legal.
You have to provide a valid siren number (9 digits in a row) and a name.
Unlike the siren, the name is only used to help you identify the user.
To create a natural user use POST /api/v6/users/natural
You have to provide a firstname, lastname and birth_date
When you create a user you will get a unique id. You should store this id in your system to interact with the user later on.
Users are not required to be unique, only the id is.
For both types of users you can also provide a group. If not provided the group default is assigned.
Listing your users
The REST endpoint GET /api/v6/users gives you a paginated list of your users.
Each entry is an object representing either a legal user, or a natural user.
Legal User object
| Field | Type | Description |
|---|---|---|
| id | uuid | Unique id of the user |
| type | string | Type of user ("LEGAL" here) |
| group | string | Group name of the user. |
| created_at | datetime | Creation date of the user |
| siren | string | Registration number of the company. Used to synchronize official data |
| name | string | Name of the company. The name is for display purpose only, it is not used in the synchronization process |
| return_url | string | The url on your system where the user is redirected when the authorizations process is finished |
| redirect_url | string | Where to redirect the user to start the authorizations process. It will create the path allowing connections to the available and enable data providers that need user authorizations. |
Natural User object
| Field | Type | Description |
|---|---|---|
| id | uuid | Unique id of the user |
| type | string | Type of user ("NATURAL" here) |
| group | string | Group name of the user. |
| created_at | datetime | Creation date of the user |
| first_name | string | First name of the user |
| last_name | string | Last name of the user |
| birth_date | date | Birth date of the user |
| return_url | string | The url on your system where the user is redirected when the connection process is finished |
| redirect_url | string | Where to redirect the user to start the authorizations process. It will create the path allowing connections to the available and enable data providers that need user authorizations.
|
Update a user
Depending of the User type, you can update its informations through this REST endpoint PATCH /api/v6/users/{userId}.
- If the user is a
Legal User, you can update its name and its group. - If the user is a
Natural User, you can update its group.
Delete a user
Depending on your contract with Qard you may have a limit on the number of concurrent user. That is why you may delete users that are not used anymore.
To delete a user use DELETE /api/v6/users/{userId}
Deleting a user is irreversible and means you won't be able to access the data of that user anymore.