The invite workflow, also known as the pre-register journey, empowers applications to invite users to activate their accounts when self-registration isn't the preferred or supported registration method.

The typical invite workflow comprises the following steps:

1. Pre-Register

In this stage, your application team creates the user account, which is pre-filled with a limited set of known data, such as the email address, first name, and last name. Upon successful pre-registration, an email or SMS with account activation information is sent to the user.

If a user record already exists and the application is not trying to resend the invite (meaning the resend parameter is not set to true), the following will occur:

The user record will be linked to the requesting application/property using the client ID.
If the requesting client ID utilizes the resourceAccess attribute, it will be added to the user record as true.
The response code for this scenario will be 200, and the UUID of the user will be provided as the response to the pre-register call.
The pre-register endpoint will ignore any form fields passed into the call. This ensures that existing user details, such as names and other information, will not be overwritten by this call.

Read more about pre-registering your users via the Pre-Register API.

2. Activate

Once the account has been successfully pre-registered, the user receives an email or SMS containing instructions to activate their account.

For users who receive the link via email:

Clicking or tapping the link in the email will direct the user to a screen with a button to "Activate Account."
The user will proceed to the next step after clicking the "Activate Account" button.

For users who receive the link via SMS or for those who have clicked the "Activate Account" button:

The user will be directed to the activation screen. This screen requests additional user information necessary to finalize account registration, such as address and password.
The user will also be prompted to review and accept relevant terms and conditions or privacy notices.

This updated flow ensures a seamless and user-friendly experience for all users, regardless of how they receive their activation link.

Endpoint URL

 curl --location 'https:///id.eu.nextreason.com/idp/v1/account/pre-register' \
--header 'Content-Type: application/json' \
--header 'Authorization: REDACTED \
--data-raw '{
   "client_id": "{{client_id}}",
   "scope": "openid",
   "auth_type": "email",
   "redirect_uri": "{{redirect_uri}}",
   "grant_type": "password",
   "profile_fields": {
       "emailAddress": "{{email}}",
       "firstName": "{{first_name}}",
       "lastName": "{{last_name}}"
   },
   "locale": "en-US"
}'

Required Parameters

The following parameters must be included on every request.

Parameter	Description
Basic Authorization Header	Client ID and Client Secret is used to Authorize the pre-register request
`client_id`	The ID used to authenticate the API call.
`scope`	OpenID Connect requests must contain the OpenID `scope` value. If the OpenID `scope` value is not present, the behavior is entirely unspecified. Other scope values may be present. Scope values used that are not understood by an implementation should be ignored. The "`openid`" default value will be used if no specific scope value is known.
`redirect_uri`	Configures the URL the user is redirected after a successful authentication. Important note: Ensure the URL is included in the list of allowed URLs for your integration. Contact your Next Reason consultant for assistance with adding URLs to the allowlist
`auth_type`	Used to identify the authentication type to be used for a particular user. The allowed values are `email` or `sms`.
`grant_type`	The type of credential to use for login. The allowed value is `password`.
`profile_fields`	Required key-value pairs for populating a user's profile. These key-value pairs are part of your onboarding configuration and it will depend on the settings configured for the client. For example, if the `auth_type` is `email`, the `profile_field` attribute is `emailAddress`; if the `auth_type` is `sms` the `profile_field` attribute is `mobilePrimary`. Additional attributes, such as company name or resource access, can also be included in this field.

Optional Parameters

Parameter	Description
`locale`	Language to use for transactional messages. examples: en-US, fr-FR. This defaults to the value defined in the default_locale setting if not passed. If the default_locale setting is not defined it will default to en-US.
`resend`	This parameter resends the invite link for both mobile and email, but will ignore whether the user already exists or not. The default value is false.

Response Handling

Upon execution of the /pre-register endpoint, two possible responses may occur:

201 Created: The user is successfully created, and an activation email or SMS will be sent to the user.
200 OK: The user already exists in the database, and no activation email will be sent.

Additionally, a UUID will be returned after a successful /pre-register call.

Configuration Options

The profile_fields are customizable based on the requirement.

Profile Fields	Description
Company Name	Allows the client to add Company Name in the user profile
Resource Access	If client has added a resource access attribute as required, the resource access field should be added in the `profile_fields`
`mobilePrimary`	The profile field needed if authentication method is `sms`.

Error Handling

Code	Error	Cause
403 Forbidden	Forbidden	Incorrect `client_id` or client secret
422 Unprocessable Entity	Invalid parameters	Missing profile fields
422 Unprocessable Entity	Invalid User - Account is already verified	If you send the resend = true parameter for account that is already verified
422 Unprocessable Entity	Invalid User - Account doesn’t exist	If you send the resend = true parameter for account that is not existing yet

Security Considerations

Basic Authorization is needed in order to perform /pre-register endpoints. It is crucial to secure the Basic Authorization credentials (Client ID and Secret) to prevent unauthorized access. Ensure that the responses that are considered as personally identifiable information (PII) is transmitted securely over HTTPS to prevent interception by unauthorized parties.

Integration

Implement the /pre-register endpoint to facilitate user invitations directly from the application via API.

If a user exists in the system, the following actions will occur:

The user will be associated with the new property from which the invitation is sent.
The UUID of the existing user will be returned in the API response for the pre-register call.
Client settings will be checked, and the resourceAccess flag (if relevant) will be set for the specific new invite client in the user record, ensuring the user can access the application without issues.
The pre-register endpoint will ignore any form fields passed into the call (e.g., the user’s name and other details will not be overwritten).