1 of 16

Migration to UsersOrchestrator API

Introduction

This section outlines the process to be followed in order to migrate from the old UserAPI endpoints to the new UsersOrchestratorAPI endpoints. This section also shows a comparison of the old and new APIs.

The endpoints covered in this section are as listed below:

Get By Id
Get By Email
Get By Query String
Get By Encrypted Email
Get By Encrypted Id
Get By Token
Create User
Create Passwordless User
Update User
Update Password
Update Email
Authenticate / Authenticate By Token
ForgotPassword
Verify Email
Send Verification Code

ProxyAPI Information

In order to redirect to UserAPI or to UsersOrchestratorAPI, ProxyAPI must have the following settings in place:

MG2 Control Internal setting, UsersOrchestrator - Its value includes a "string.Format" that must be utilized to determine the correct API route. The value by default is "{0}/UsersOrchestrator".

Note: Since the ProxyAPI directly calls the UsersOrchestratorAPI, GatewayAPI is not involved in the request chain.

IgnoreProvider Considerations

This flag is included in the Body or QueryString of certain endpoints.
This parameter is used to retrieve only SubscribeRegistration results while ignoring third-party integration services. This is an optional parameter that modifies the workflow execution.

User States

The UserOrchestrator API also includes the registration status in the API response.

The GET /Users and GET /Users/id endpoints will include the output parameter, State, which returns the status of a registration.
- The registration's status will be returned as follows:
  - If the tenant has been associated with a third-party authentication system such as Auth0, Firefly, etc., the State will be returned as Standard.
  - If the tenant has been associated with MG2 Auth:
    When the Password field in the database remains blank, the State will be Lite.
    When the Verified field in the database has been set to False, the State will be Unverified.
    When the Password field hasn't been blank and the Verified field has been set to true, the State will be Standard.
The POST /Users endpoint will display an error when trying to create a registration that already exists in the database and has the Verified field set to false.
The POST /Users/Authentication endpoint will display an error when trying to login with an Unverified or Lite registration.

Get By Id

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Customer Registration ID (CRID), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Note

MG2 control flow setting: Flow.UserProvider value should be set to "Auth0," "Gigya," "SSOR", or "Firefly", depending on the third-party system or integration service being used.
MG2 control flow setting, "Flow.Users.RedirectToOrchestrator", value has to be set to 1 for the ProxyAPI redirection to the UsersOrchestratorAPI instead of the UserAPI.

Comparison

Parameters

The parameter, Type, has been deprecated.
A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/{customerRegistrationId}/{type}

/v4/Users/{customerRegistrationId}/?ignoreProvider={boolean}

Method

GET

Response

Get User by Id

GET /v4/Users/{customerRegistrationId}/?ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the CustomerRegistrationId.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Name

Type

Description

CustomerRegistrationId*

String

Unique identifier for the user in the authentication provider.

Query Parameters

Name

Type

Description

IgnoreProvider

Boolean

Indicates whether to retrieve the user details from the integration service.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "UsersOrchestrator_S200_01",
        "text": "GetById completed.",
        "type": "Success"
    },
    "data": {
        "customerRegistrationId": "string",
        "encryptedCustomerRegistrationId": "string",
        "email": "string",
        "verified": true,
        "state": "UserStates",
        "lastLogoutDate": "Date",
        "firstName": "string",
        "lastName": "string",
        "metadata": {
            "title": "",
            "phoneNumber": "",
            "gender": "",
            "age": "",
            "dob": "",
            "dobYYYY": "",
            "acceptsEmailOffers": "",
            "acceptsEmailAds": "",
            "acceptsEmailPromotions": "",
            "address": "",
            "city": "",
            "country": "",
            "position": "",
            "isOkToEmail": "",
            "isOkToPhone": "",
            "isOkToMail": "",
            "workPhone": "",
            "timeZone": "",
            "scoreMember": "",
            "companyName": "",
            "postalCode": "",
            "cellPhone": "",
            "acceptsEENotification": "",
            "ebill_flag": "",
            "eadvan_flag": "",
            "eedition_flag": "",
            "ee_email_flag": "",
            "promo_flag": "",
            "feat_flag": "",
            "dealdigger_flag": "",
            "ads_flag": "",
            "member_event_flag": "",
            "contentEngagement_flag": "",
            "subcom_flag": "",
            "survey_flag": "",
            "accountUpdates_flag": "",
            "photo": "",
            "displayName": "",
            "optOutMarketing": "",
            "agreeToTerms": "",
            "bounceType": "",
        },
        "addDate": "Date",
        "addSource": "string",
        "changeDate": "Date",
        "changeSource": "string"
    }
}

Error Code: UsersOrchestrator_E400 Error Message: Bad Request
Error Code: UsersOrchestrator_E400_01
Error Message: Invalid Id

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_01
Error Message: There was a problem during the GetById workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

CREATELOGIN (68)

No user will be created but synchronized in our database

GETUSERBYID (1042)

AUTHSYSTEM_USER_GETBYID (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

SUBSCRIBE_USER_GETBYID (4001)

New event created to get User By Id from Subscribe

SUBSCRIBE_USER_UPDATE (4004)

New event created to update User in Subscribe

Get By Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Email (Subscriber’s email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Comparison

Parameters

The parameter, Type, has been deprecated.
A new parameter, IgnoreProvider, has been added.

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/{type}?email={email}

/v4/Users?email={email}&ignoreProvider={boolean}

Method

GET

Response

Get By Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Email.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Name

Type

Description

IgnoreProvider

Boolean

Indicates whether to retrieve the user details from the integration service.

Email*

String

Subscriber’s email.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "UsersOrchestrator_S200_02",
        "text": "Get completed.",
        "type": "Success"
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "firstName": "string",
            "lastName": "string",
            "state": "UserStates",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            },
            "verified": true
        }
    ],
    "meta": {
        "totalRecords": 0
    }
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400 Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

GETUSER (73)

AUTHSYSTEM_USER_GET (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

CREATELOGIN (68)

No user will be created but synchronized in our database

SUBSCRIBE_USER_UPDATE (4004)

New event to update User in Subscribe

SUBSCRIBE_USER_GET (4000)

New event to retrieve User from Subscribe

Get By Query String

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to retrieve the user's information based on the provided Query String parameters.

Based on the value of Flow.UserProvider and the IgnoreProvider input parameter, the API gives user information in the following way:

If no valid value is provided in Flow.UserProvider, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to True, the API retrieves user information from the Subscribe Registration API.
If a valid value is provided in Flow.UserProvider and the input parameter IgnoreProvider is set to False, the user's details are retrieved from both the integration service and the subscribe registration. The combined information is displayed in the response.

Note

MG2 control flow setting: Flow.UserProvider value should be set to "Auth0," "Gigya," "SSOR", or "Firefly", depending on the third-party system or integration service being used.
MG2 control flow setting, "Flow.Users.RedirectToOrchestrator", value has to be set to 1 for the ProxyAPI redirection to the UsersOrchestratorAPI instead of the UserAPI.

Comparison

Parameters

The following parameters have been deprecated.
1. Type
2. OnlyActive
3. SortBy
4. SortOrder
5. UsersPerPage
6. LookupInUserProvider
7. AuthSystemId
A set of new parameters has been added.
1. PageSize
2. OrderBy
3. OrderByType
4. IgnoreProvider

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/{queryString}

/v4/Users/{queryString}

Method

GET

Response

Get User by Query String

GET /v4/Users/{queryString}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the provided Query String parameters.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Name

Type

Description

CustomerRegistrationId*

String

Unique identifier for the user in the authentication provider.

Query Parameters

Name

Type

Description

IgnoreProvider

Boolean

Indicates whether to retrieve the user details from the integration service.

EncryptedEmail

String

Encrypted email of the user

String

Email or partial email address of the user

PageSize

Integer

Maximum number of items returned per request.

Default value 10.

PageNumber

Integer

Requested page number of pagination. Default value 1.

OrderByType

Integer

Sort the records in ascending (0) or descending (1) order.

OrderBy

Integer

Sort the records based on the column number.

FirstName

String

User’s first name.

LastName

String

User’s last name.

Metadata

Dictionary <String, String>

Since it is a dictionary query parameter, each "Key-Value" pair must be sent individually with the prefix "metadata.".

For example, if the purpose is to filter users based on their first and last names, the query string will be: https://UrlBase/Users?metadata.firstName=FirstName&metadata.lastName=LastName”

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "UsersOrchestrator_S200_02",
        "text": "Get completed.",
        "type": "Success"
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "firstName": "string",
            "lastName": "string",
            "state": "UserStates",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            },
            "verified": true
        }
    ],
    "meta": {
        "totalRecords": 0
    }
}

Error Code: UsersOrchestrator_E400 Error Message: Bad Request
Error Code: UsersOrchestrator_E400_02
Error Message: Invalid InputModel

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

SUBSCRIBE_USER_GET (4000)

New event created to get User from Subscribe

Get By Encrypted Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API.

With the input parameter Encrypted Email (Subscriber’s encrypted email), the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/Encrypted?encryptedEmail={encryptedEmail}

/v4/Users?encryptedEmail={encryptedEmail}

Method

GET

Response

Get By Encrypted Email

GET /v4/Users?email={email}&ignoreProvider={boolean}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Email.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Name

Type

Description

Email*

String

Subscriber’s email.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "string",
        "text": "string",
        "type": 0
    },
    "meta": {
        "totalRecords": 0
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "verified": true,
            "firstName": "string",
            "lastName": "string",
            "state": "UserState",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            }
        }
    ]
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400
Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

GETUSER (73)

AUTHSYSTEM_USER_GET (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

CREATELOGIN (68)

No user will be created but synchronized in our database

SUBSCRIBE_USER_UPDATE (4004)

New event to update User in Subscribe

SUBSCRIBE_USER_GET (4000)

New event to retrieve User from Subscribe

Get By Encrypted Id

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Encrypted Customer Registration ID.

With the input parameter Encrypted CRID, the API gets the user's information from both the integration service and the subscribe registration. The response displays the combined information.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

URL

/User/Encrypted/{Type}?encryptedCustomerRegistrationId={encryptedCustomerRegistrationId}

/v4/Users?encryptedCustomerRegistrationId={encryptedCustomerRegistrationId}

Method

GET

Response

Get By Encrypted ID

GET /v4/Users?encryptedCustomerRegistrationId={encryptedCustomerRegistrationId}

This endpoint is used to gets the user's information from both the integration service and the subscribe registration based on the Encrypted Customer Registration ID.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Query Parameters

Name

Type

Description

Encrypted Customer Registration ID*

String

Encrypted unique identifier for the user in authentication system.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

{
    "message": {
        "code": "string",
        "text": "string",
        "type": 0
    },
    "meta": {
        "totalRecords": 0
    },
    "data": [
        {
            "customerRegistrationId": "string",
            "encryptedCustomerRegistrationId": "string",
            "email": "string",
            "verified": true,
            "firstName": "string",
            "lastName": "string",
            "state": "UserState",
            "metadata": {
                "title": "",
                "phoneNumber": "",
                "gender": "",
                "age": "",
                "dob": "",
                "dobYYYY": "",
                "acceptsEmailOffers": "",
                "acceptsEmailAds": "",
                "acceptsEmailPromotions": "",
                "address": "",
                "city": "",
                "country": "",
                "position": "",
                "isOkToEmail": "",
                "isOkToPhone": "",
                "isOkToMail": "",
                "workPhone": "",
                "timeZone": "",
                "scoreMember": "",
                "companyName": "",
                "postalCode": "",
                "cellPhone": "",
                "acceptsEENotification": "",
                "ebill_flag": "",
                "eadvan_flag": "",
                "eedition_flag": "",
                "ee_email_flag": "",
                "promo_flag": "",
                "feat_flag": "",
                "dealdigger_flag": "",
                "ads_flag": "",
                "member_event_flag": "",
                "contentEngagement_flag": "",
                "subcom_flag": "",
                "survey_flag": "",
                "accountUpdates_flag": "",
                "photo": "",
                "displayName": "",
                "optOutMarketing": "",
                "agreeToTerms": "",
                "bounceType": "",
            }
        }
    ]
}

Error Code: UsersOrchestrator_E400_02 Error Message: Invalid InputModel
Error Code: UsersOrchestrator_E400
Error Message: Bad Request

Error Code: UsersOrchestrator_E500 Error Message: Internal Server Error
Error Code: UsersOrchestrator_E500_02
Error Message: There was a problem during the Get workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

GETUSER (73)

AUTHSYSTEM_USER_GET (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

CREATELOGIN (68)

No user will be created but synchronized in our database

SUBSCRIBE_USER_UPDATE (4004)

New event to update User in Subscribe

SUBSCRIBE_USER_GET (4000)

New event to retrieve User from Subscribe

Get By Token

Introduction

This endpoint retrieves the user's information from both the integration service and the subscribe registration based on the input parameter Token (access token generated in the consumer application).

UsersOrchestrator doesn’t support this operation.

Current Proxy URL: POST User/Token

Create User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

URL

/User

/v4/Users

Method

POST

Request

Response

Create User

POST /v4/Users

This endpoint is used to create a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

Request Body

Name

Type

Description

String

Subscriber’s email.

Metadata

Object

Metadata must be an object in camelCase format.

LastName

String

Subscriber’s last name.

FirstName

String

Subscriber’s first name.

IgnoreProvider

Boolean

If the IgnoreProvider flag is false, it executes a Create operation through the ThirdParty system (Integration).

If the IgnoreProvider flag is true, it executes a Create operation through the SubscribeRegistration API (Subscribe).

ReturnUrl

String

URL to which users must be redirected after they have successfully verified their registration.

VerifyEmail

Boolean

Default false.

If True is provided, then the registration will not be created right away. Naviga would wait until the user confirmed the registration by clicking the link in the verification email.

Password

String

Subscriber’s password.

EncryptedCustomerRegistrationid

String

Encrypted unique identifier for the user in authentication system.

CustomerRegistrationId

String

Unique identifier for the user in the authentication provider

{
  "message":{
      "code": "UsersOrchestrator_S200_06",
      "text": "Create completed.",
      "type": "Success"
  },
  "data": {
      "customerRegistrationId": "string",
      "encryptedCustomerRegistrationId": "string"     
  }
}

Status Code

Code

Message

400

UsersOrchestrator_E400

Bad Request

400

UsersOrchestrator_E400_00

Invalid InputModel - {Message}

400

UsersOrchestrator_E400_07

The entered email address is still pending for verification.

400

UsersOrchestrator_E400_08

The email is already in use by another user.

400

UsersOrchestrator_E400_09

The metadata is invalid.

400

UsersOrchestrator_E400_17

Metadata Key or Value cannot contain more than 100 characters.

400

UsersOrchestrator_E400_23

The customer registration id already exists.

500

UsersOrchestrator_E500

Internal Server Error

500

UsersOrchestrator_E500_01

There was a problem during the GetById workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

GETUSER (73)

AUTHSYSTEM_USER_GET (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

CREATELOGIN (68)

AUTHSYSTEM_USER_CREATE (4602)
SUBSCRIBE_USER_CREATE (4002)

For each CREATELOGIN old event, we now create two events. One is for the call to the third-party system, and the other is for the call to our database.
SUBSCRIBE_USER_CREATE is responsible for sending the email.

Create Passwordless User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to create a user.

Comparison

When creating a passwordless user, UsersOrchestrator will generate a dummy password and the proper Change Password URL.

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

URL

/User/Passwordless

/v4/Users

Method

POST

Request

Response

Create Passwordless User

POST /v4/Users

This endpoint is used to create a user without a password.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Name

Type

Description

Authorization*

String

JSON Web Token used for security purposes

X-SourceSystem*

String

To identify the consumer or the Source System

X-ClientCode*

String

Client Code of the Tenant

X-PaperCode*

String

Paper Code of the Tenant

X-ClientGroupCode*

String

Client Group Code of the Tenant

Request Body

Name

Type

Description

String

Subscriber’s email.

CustomerRegistrationId

String

Unique identifier for the user in the authentication provider

EncryptedCustomerRegistrationid

String

Encrypted unique identifier for the user in authentication system.

VerifyEmail

Boolean

Default false.

If True is provided, then the registration will not be created right away. Naviga would wait until the user confirmed the registration by clicking the link in the verification email.

ReturnUrl

String

URL to which users must be redirected after they have successfully verified their registration.

FirstName

String

Subscriber’s first name.

LastName

String

Subscriber’s last name.

Metadata

Object

Metadata must be an object in camelCase format.

IgnoreProvider

Boolean

If the IgnoreProvider flag is false, it executes a Create operation through the ThirdParty system (Integration).

If the IgnoreProvider flag is true, it executes a Create operation through the SubscribeRegistration API (Subscribe).

{
    "message": {
        "code": "UsersOrchestrator_S200_06",
        "text": "Create completed.",
        "type": "Success"
    },
    "data": {
        "customerRegistrationId": "string",
        "encryptedCustomerRegistrationId": "string"
    }
}

Status Code

Code

Message

400

UsersOrchestrator_E400

Bad Request

400

UsersOrchestrator_E400_00

Invalid InputModel - {Message}

400

UsersOrchestrator_E400_07

The entered email address is still pending for verification.

400

UsersOrchestrator_E400_08

The email is already in use by another user.

400

UsersOrchestrator_E400_09

The metadata is invalid.

400

UsersOrchestrator_E400_17

Metadata Key or Value cannot contain more than 100 characters.

400

UsersOrchestrator_E400_23

The customer registration id already exists.

500

UsersOrchestrator_E500

Internal Server Error

500

UsersOrchestrator_E500_01

There was a problem during the GetById workflow.

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Current

New

Note

GETUSER (73)

AUTHSYSTEM_USER_GET (4601)

Renamed.

This event retrieves a User by Id from AuthSystem.

CREATELOGIN (68)

AUTHSYSTEM_USER_CREATE (4602)
SUBSCRIBE_USER_CREATE (4002)

For each CREATELOGIN old event, we now create two events. One is for the call to the third-party system, and the other is for the call to our database.
SUBSCRIBE_USER_CREATE is responsible for sending the email.

Update User

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update a user based on the provided CustomerRegistrationId.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

Update User

PUT /v4/Users/{customerRegistrationId}/

This endpoint is used to update a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Update Password

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update the password of a user based on the provided CustomerRegistrationId.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

Update Password

PATCH /Users/{{customerRegistrationId}}/Password

This endpoint is used to update the password of a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Name

Type

Description

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Update Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to update the email of a user based on the provided CustomerRegistrationId.

Comparison

Note: The old model is in PascalCase, while the new model is in CamelCase.

User API

Users Orchestrator API

Update Email

PATCH /v4/Users/{CustomerRegistrationId}/Email

This endpoint is used to update the email of a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Name

Type

Description

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Authenticate/Authenticate By Token

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to authenticate a user.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
Cookie tokens will not be returned by the UsersOrchestrator API.
For custom fields, use Metadata.

User API

Users Orchestrator API

Authenticate

POST /v4/Users/Authentication

This endpoint is used to authenticate a user.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

ForgotPassword

ForgotPassword (Start)

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and the Subscribe Registration API to create the STARTFORGOTPASSWORD (PWDREQ) event and send an email with a link to the subscriber.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
UsersOrchestrator API doesn’t return PasswordResetLinkSent.

User API

Users Orchestrator API

ForgotPassword (Start)

POST /v4/Users/ForgotPassword

This endpoint is used to create the STARTFORGOTPASSWORD (PWDREQ) event and send an email with a link to the subscriber.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

ForgotPassword (Validate)

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and the Subscribe Registration API to validate whether the received EncryptedEventId is a valid event for the forgot password flow.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
The UsersOrchestrator API returns the EventId associated with the user.
If the event is invalid, the UsersOrchestrator API returns an error.

Forgot Password (Validate)

GET /v4/Users/ForgotPassword/{{EncryptedEventId}}/Validity

This endpoint is used to validate whether the received EncryptedEventId is a valid event for the forgot password flow.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Headers

ForgotPassword (FINISH)

Introduction

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
If the flow fails, the UsersOrchestrator API returns an error.

ForgotPassword (Finish)

POST /v4/Users/ForgotPassword/{{EncryptedEventId}}

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Path Parameters

Headers

Request Body

Error Code: UsersOrchestrator_E400

Error Message: Bad Request

Error Code: UsersOrchestrator_E400_02

Error Message: Invalid InputModel

Error Code: UsersOrchestrator_E500

Error Message: Internal Server Error

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.

Verify Email

Introduction

This endpoint handles the workflow orchestration between the integration services (such as Auth0, Gigya, SSOR, and Firefly) and Subscribe Registration API to verify the email of a user based on the provided Email and Verification Code.

Comparison

Note:

The old model is in PascalCase, while the new model is in CamelCase.
The UsersOrchestrator API only returns CRID and EncryptedCRID and does not return cookie tokens.

User API

Users Orchestrator API

Verify Email

POST /v4/Users/Verification

This endpoint is used to verify the email of a user based on the provided Email and Verification Code.

Note: The parameters marked with an asterisk (*) are mandatory and must be included in the input model.

Headers

Request Body

Events

Note:– The associated Event IDs for the Event Type Codes are specified in parentheses (i.e., EventTypeCode (EventID)) in the table below.