User Addresses management
Through the API
We’ve added a new way to manage Users' addresses in version 2.25 via the new id
field.
To read addresses
The two endpoints below allow you to retrieve the information present in the addresses
object or a particular address
item, from the User data model, no matter if the account is lite or managed.
# User addresses GET /api/v2/users/{userId}/addresses/addressId GET /api/v2/users/{userId}/addresses
To create addresses
You have the ability to create addresses using the endpoints below. Be sure to use the correct endpoint, depending on the user’s profile type.
For a lite profile:
POST /api/v2/lite-users/{userId}/addresses
For a managed profile:
POST /api/v2/managed-users/{userId}/addresses
Those endpoints will create a new address
item into the addresses
object of the User data model.
Specifics for id
and default
fields
The id
field is set automatically so you don’t have to manage this aspect. You can reuse ids to update a user’s address
items (see further).
The default
field is set automatically to true
for an address if:
-
There is only one item in the
addresses
object -
The field is specified in the payload with the value
true
There can be only one default address at a time. So if you add or update an address with the field default: true
, then other addresses will be set to default: false
.
To update addresses
You can update addresses by using an equivalent method as for creating them, but providing an addressId
in the endpoint call.
For a lite profile:
POST /api/v2/lite-users/{userId}/addresses/{addressId}
For a managed profile:
POST /api/v2/managed-users/{userId}/addresses/{addressId}
These endpoints will update the address
item corresponding to the addressId
you provided.
To delete addresses
For addresses deletion, you have two approaches:
-
Delete an address by providing its
id
, -
Delete all the addresses of a user at once.
Specific address deletion
For a lite profile:
DELETE /api/v2/lite-users/{userId}/addresses/{addressId}
For a managed profile:
DELETE /api/v2/managed-users/{userId}/addresses/{addressId}
Global user addresses deletion
For a lite profile:
DELETE /api/v2/lite-users/{userId}/addresses
For a managed profile:
DELETE /api/v2/managed-users/{userId}/addresses
For more information on the API usage for Addresses, see the documentation of API Management for Addresses.
Through the CSV Import module
To create addresses
The addresses.x.id
column is not mandatory in the CSV file as the id
will be generated during processing anyway.
Nevertheless, it is technically possible to specify it in the file, but in the process of creation (i.e. in the absence of an existing address with this id
), the value will be ignored.
We generate the id
field for addresses on the basis of a numerical sequence starting at 0.
Example:
email,given_name,family_name,gender,birthdate,default,locality,postal_code,addresses.0.id,addresses.0.default,addresses.0.street_address,addresses.0.postal_code,addresses.0.locality,addresses.0.country,addresses.1.default,addresses.1.street_address,addresses.1.postal_code,addresses.1.locality,addresses.1.country
bx@import.com,B,X,male,1970-01-01,false,Paris,75001,0,false,12 rue de la Boétie,75001,Paris,France,true,18 rue du Général Leclerc,75004,Paris,France
Here, addresses.0
has a specified id
while addresses.1
does not. Since we are in a creation process, assuming there is no address registered for this User, the provided id
is ignored and the application generates the ids (0 and 1) itself for both addresses.
To update addresses
In the update process, it is mandatory to specify the addresses.x.id
field to make modifications to an existing address.
Using the same example:
email,given_name,family_name,gender,birthdate,default,locality,postal_code,addresses.0.id,addresses.0.default,addresses.0.street_address,addresses.0.postal_code,addresses.0.locality,addresses.0.country,addresses.1.default,addresses.1.street_address,addresses.1.postal_code,addresses.1.locality,addresses.1.country
bx@import.com,B,X,male,1970-01-01,false,Paris,75001,0,false,12 rue de la Boétie,75001,Paris,France,true,18 rue du Général Leclerc,75004,Paris,France
Here, addresses.0
has a specified id
while addresses.1
does not.
In this update process, we assume addresses.0
already existed and was the only address registered while addresses.1
did not.
addresses.0
will be modified only on the values specified in the file whereas addresses.1
will be created with the values specified in the file.