Skip to main content

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

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.

FieldTypeDescription
namestringMandatory, used for you to identify your user
sirenstringOptional, registration code of your user's company. Must be a SIREN code over 9 digits if not left out and country is France
postal_codestringOptional, postal code of the user's city
countrystringOptional, 2-letter code of the user's country. Defaults to "FR" (France) if left blank, or left out.
ape_codestringOptional, Activity code of the user
groupstringOptional, the group name is meant for you to segment your users. Defaults to "default" if left out.
return_urlstringOptional, 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.

FieldTypeDescription
firstnamestringMandatory, first name of you user
lastnamestringMandatory, original surname of you user (usually their birth surname).
birth_datedateBirth date of the user
groupstringOptional, the group name is meant for you to segment your users. Defaults to "default" if left out.
return_urlstringOptional, 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.

FieldTypeDescription
iduuidUnique id of the user
typestringType of user ("LEGAL" here)
groupstringGroup name of the user.
created_atdatetimeCreation date of the user
sirenstringRegistration number of the company. Used to synchronize official data
namestringName of the company. The name is for display purpose only, it is not used in the synchronization process
return_urlstringThe url on your system where the user is redirected when the authorizations process is finished
redirect_urlstringWhere 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

FieldTypeDescription
iduuidUnique id of the user
typestringType of user ("NATURAL" here)
groupstringGroup name of the user.
created_atdatetimeCreation date of the user
first_namestringFirst name of the user
last_namestringLast name of the user
birth_datedateBirth date of the user
return_urlstringThe url on your system where the user is redirected when the connection process is finished
redirect_urlstringWhere 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.