Import And Migration

Retrieving password migration retention configuration

get

Retrieves the password migration retention configuration for the tenant.

Required scopes

This endpoint requires the following scopes:

: Needed to retrieve password migration retention configuration.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Responses

200

application/json

retentionEndDatestring · dateOptional

Date when the password migration retention window ends.

emailReminderDatestring · dateOptional

Date when reminder emails are sent to unmigrated customers.

emailNotificationsEnabledbooleanOptional

Flag indicating whether customers receive email notifications about the migration process. When true, customers receive reminder and password reset emails. When false, customers do not receive any emails regarding the migration.

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

404

Password migration retention configuration is not set for the tenant.

get/customer/{tenant}/config/password-migration-retention

GET /customer/{tenant}/config/password-migration-retention HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "retentionEndDate": "2027-01-31",
  "emailReminderDate": "2027-01-24",
  "emailNotificationsEnabled": true
}

Configuring password migration retention

post

Creates or updates the password migration retention configuration for the tenant.

Use this configuration before importing customers with legacyAuth. For customers with legacyAuth, legacy password hashes are silently migrated to Emporix hashes on the first successful login. When the retention period ends, remaining unmigrated accounts require a password reset and legacy credentials are cleared. A password reset email is sent to affected customers when emailNotificationsEnabled is true. An email reminder requesting a single login is sent on emailReminderDate to all unmigrated customers when emailNotificationsEnabled is true, asking them to log in once so their accounts can be migrated.

If emailReminderDate is omitted, the service defaults to 7 days before retentionEndDate, or to tomorrow when that default would fall on or before today. If emailNotificationsEnabled is omitted, the service defaults to true. When false, customers do not receive any emails regarding the migration.

If emails should include links to the storefront (password reset or login page), or a non-standard email template is required, please contact Emporix support.

Required scopes

This endpoint requires the following scopes:

: Needed to configure password migration retention and import customers in bulk.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Body

retentionEndDatestring · dateRequired

Future date when the password migration retention window ends.

emailReminderDatestring · dateOptional

Optional date on or after today and before retentionEndDate when reminder emails are sent to unmigrated customers. When omitted, defaults to 7 days before retentionEndDate, or to tomorrow when that default would fall on or before today.

emailNotificationsEnabledbooleanOptional

Optional flag indicating whether customers receive email notifications about the migration process. When true, customers receive reminder and password reset emails. When false, customers do not receive any emails regarding the migration. When omitted, defaults to true.

Default: true

Responses

200

application/json

retentionEndDatestring · dateOptional

Date when the password migration retention window ends.

emailReminderDatestring · dateOptional

Date when reminder emails are sent to unmigrated customers.

emailNotificationsEnabledbooleanOptional

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

500

Configuration could not be saved.

post/customer/{tenant}/config/password-migration-retention

POST /customer/{tenant}/config/password-migration-retention HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99

{
  "retentionEndDate": "2027-01-31",
  "emailReminderDate": "2027-01-24",
  "emailNotificationsEnabled": true
}

{
  "retentionEndDate": "2027-01-31",
  "emailReminderDate": "2027-01-24",
  "emailNotificationsEnabled": true
}

Removing password migration retention configuration

delete

Removes the password migration retention configuration for the tenant.

To avoid indefinite storage of potentially sensitive legacy password hashes, the configuration removal is blocked while any customer account still contains a legacyAuth record. Complete the migration window first. The configuration may still be updated to move the retentionEndDate earlier and complete migration sooner.

Required scopes

This endpoint requires the following scopes:

: Needed to configure password migration retention and import customers in bulk.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Responses

204

No Content

No content

400

Configuration removal is not possible until password migration is concluded.

application/json

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

delete/customer/{tenant}/config/password-migration-retention

DELETE /customer/{tenant}/config/password-migration-retention HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Importing customers in bulk

post

Imports multiple customer profiles in a single request. The maximum batch size is 200.

Each item must include an account object with exactly one of:

passwordHash — a precomputed password hash compatible with the Emporix password hashing strategy. In order to determine if your existing strategy is compatible, please contact Emporix support.
legacyAuth — a legacy password hash (incompatible with the Emporix password hashing strategy) and algorithm metadata for lazy rehash on first successful login. In order to establish the required algorithm metadata for your case, please contact Emporix support.

To avoid indefinite storage of potentially sensitive legacy password hashes, importing customers with legacyAuth requires an active password migration retention configuration for the tenant.

Response for a particular customer is returned at the same position (index) at which that customer is located in the request body.

Required scopes

This endpoint requires the following scopes:

: Needed to configure password migration retention and import customers in bulk.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Bodyall of[]

titlestringOptional

firstNamestringOptional

middleNamestringOptional

lastNamestringOptional

contactPhonestringOptional

companystringOptional

preferredLanguagestringOptional

Customer preferred language.

Default: en_US

preferredCurrencystring · min: 3 · max: 3Optional

Customer preferred currency, compliant with the ISO 4217 standard.

Default: USD

preferredSitestringOptional

Customer preferred site.

Default: main

typestringOptional

User type. Supported values are: CUSTOMER and CONTACT. If the field is empty then the user is considered as a customer.

photoUrlstringOptional

Url of a picture.

restrictionstring · nullableOptional

Access control identifier that determines who can view or manage the customer.

Purpose: Restricts customer visibility based on scope permissions. Only users/applications with matching restriction scopes can access customers with a specific restriction value.

Access Control:

Reading: Users can only query and view customers with the restriction value that matches one of their authorized restrictions.

Validation: The value must exist in the tenant's configured list of valid restrictions.

Site Synchronization: If the restriction property is not set with tenant configuration property enableSyncBetweenRestrictionsAndSiteCodes set to true, the restriction field automatically syncs with preferredSite property.

Example: DE

idstring · min: 1 · max: 66Optional

Custom customer identifier. If not provided, it is automatically generated.

Pattern: ^[\w-]{1,66}$

contactEmailstringOptional

Optional contact email. When provided, it must match account.email (case-insensitive). If omitted, account.email is used as the contact email.

Responses

207

Multi-Status

application/json

indexintegerOptional

Index of the processed item, matching the item position in the request body.

idstringOptional

Customer number generated for a successfully imported customer.

codeintegerOptional

HTTP status code for the processed item.

statusstringOptional

HTTP status description for the processed item.

messagestringOptional

Error message when the item failed.

400

Request was syntactically incorrect. Details will be provided in the response payload.

application/json

401

Unauthorized

application/json

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

application/json

post/customer/{tenant}/customers/import

POST /customer/{tenant}/customers/import HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 240

[
  {
    "contactEmail": "john.doe@emporix.com",
    "firstName": "John",
    "lastName": "Doe",
    "preferredLanguage": "en_US",
    "preferredCurrency": "EUR",
    "preferredSite": "main",
    "account": {
      "email": "john.doe@emporix.com",
      "passwordHash": "1:10000:abcdefgh:ijklmnop"
    }
  }
]

[
  {
    "index": 0,
    "id": "13869000",
    "code": 201,
    "status": "Created"
  },
  {
    "index": 1,
    "code": 400,
    "status": "Bad Request",
    "message": "Exactly one of 'passwordHash' or 'legacyAuth' must be provided in the account"
  }
]

PreviousAddresses

NextModels

Last updated 21 days ago

Was this helpful?