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.