POST /process/start/{processName}

Process Start API

This API creates and initializes a unique instance of a Digital Identity Management Process. Also known as the “Process Start” API, this is the standard method of Process initiation from a client web application.

Process Naming Convention
The complete `processName` includes the category, name, and version, with each item separated by a period. For example, to invoke the Onboard User with Email & Mobile Process, version 1.0, use this API:`POST {url}/process/start/authentication.OnboardAndAuthenticate.v2.0` Refer to the individual Process topics for the full name and invocation URL of each Process.

Example API URLs

**POST** https://{your.tenant.url}/**process/start**/recovery.PasswordRecovery.v1.0
**POST** https://{your.tenant.url}/**process/start**/userManagement.UpdatePassword.v1.0
**POST** https://{your.tenant.url}/**process/start**/socialFederation.AssociateSocialMedia.v1.0

Request Parameters

For most Processes, the initial API request optionally accepts no payload. Instead, it derives its action from the name provided in the URL. The first response from most Processes is a specification of the information that the Process needs to proceed. However, certain Digital Identity Management Processes support use cases where the UI provides the required parameters upfront in the initial API request URL: POST https://{url}/process/start/{processName}.v1.0?{paramName}={paramValue}&{paramName}={paramValue} For example, when a client invokes the Onboard and Authenticate User with Social Process, the Process first responds with a request for the user’s chosen social provider, or providerID, and the response includes a list of available provider IDs. To skip this step, the application can invoke the Process with that providerId in the Process Start request URL:

POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0**?providerId=facebook**
POST /process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0**?providerId=google**

This enables a client application UI to display social media badges on the sign-in and sign-up page(s), and then invoke the proper variation when a user clicks on a badge. If you have use cases where the UI will know required data that is otherwise asked for in the first response, you can skip a step and simply provide the required information in the POST process/start/ URL.

Response Parameters

The Process Start API may return some or most of the following key properties:

`processId`	Unique identifier for the current instance of this Process. The client application UI must provide this ID in every subsequent Process Step request in order to continue and complete the Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on. In some cases, `stepName` can be useful for application UIs so that they know what page to render.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`displayMessage`	Descriptive message that the UI can optionally display to the end user.
`parameters`	Object that specifies the info this Process requires to continue its task, usually in the form of user input. The client application must provide the required data, inside the same `parameters` in the subsequent Process Step request.
`output`	Additional data object with information that Digital Identity Management provides to the client application in order to render the user interface. The information may indicate what has been done (e.g., the ID of an object which has been created), or include data useful for asking a question about the next step (e.g., a list of available options to provide to the user).For example, the Onboard and Authenticate User with Social Process initially responds with a request for the social provider’s `providerId`, and also supplies a list of available options to present to the user: `{ "parameters": { "providerId": "String" }, "output": { "providers": [ "google", "facebook", "apple" ] } }` Unlike `parameters`, the `output` object only for the client application’s consumption. In many cases, information specified in the `output` object of a response will be used in the `parameters` object of a subsequent Process Step request.
`pkat`	Unique Proof Key for Action Token (PKAT) that corresponds to an action token that has been issued and sent to a user’s contact channel (email or mobile number). The PKAT is used for OTP verification and a quick token resend functionality. See Action Tokens for more details.
`userAuthenticated`	Boolean that indicates if the user was authenticated into Digital Identity Management. Appears at the final response from a Process wherein authentication typically occurs.
This is not an exhaustive list. Data fields specified in the `parameters` and `output` objects will vary from Process to Process. You can refer to the Use Case subtopics under each Process for full, step-by-step details.

Errors

See Common Process Error Codes for more information. Error Cases under each Process also contain process-specific examples of errors.

Applicable Processes

The Process Start API is used to invoke the following Processes:

POST API Request	Process Invoked
`process/start/onboard.OnboardUserWithEmailMobile.v1.0`	Onboard User with Email and Mobile Process
`process/start/socialFederation.SocialMediaAssistedOnboarding.v1.0`	Onboard and Authenticate User with Social Account Process
`process/start/socialFederation.AssociateSocialMedia.v1.0`	Associate Social Account to User ID
`process/start/socialFederation.DissociateSocialMedia.v1.0`	Dissociate Social Account from User ID
`process/start/userManagement.AddOrUpdateAuthnIdentifier.v1.0`	Add/Update Email, Mobile, or Alias
`process/start/userManagement.RemoveUserAttribute.v1.0`	Remove User Attribute
`process/start/recovery.PasswordRecovery.v1.0`	Recover ID (a.k.a. “Forgot Password?”)
`process/start/userManagement.SendVerification.v1.0?authnIdentifier=\{authN ID\}`	Send Verification Message
`process/start/userManagement.UpdateNotificationChannel.v1.0`	Update User Notification Channel
`process/start/userManagement.UpdatePassword.v1.0`	Update Password
`process/start/accountAssociation.AssociateAccount.v2.0`	Associate Billing Account to User ID
`process/start/accountAssociation.DissociateAccount.v1.0`	Dissociate Billing Account from User ID
`process/start/entitlementManagement.ShareASF.v1.0`	Share Access to an Account, Subscription, or Feature
`process/start/entitlementManagement.RevokeUserAccess.v1.0`	Revoke Access to an Account, Subscription, or Feature
`process/start/userManagement.RemoveUser.v1.0`	Remove User from Account Group
`process/start/entitlementManagement.UserLeavesASF.v1.0`	User Leaves Account, Subscription, or Feature
`process/start/userManagement.RegisterAuthnIdentifierAsMFA.v1.0`	Register Email or Mobile as MFA
`process/start/userManagement.UnregisterAuthnIdentifierAsMFA.v1.0?authnIdentifier=\{authN ID\}`	Unregister Email or Mobile as MFA
`process/start/userManagement.registerAuthenticatorAppAsMFA.v1.0`	Register Authenticator App as MFA
`process/start/userManagement.unregisterAuthenticatorAppAsMFA.v1.0`	Unregister Authenticator App as MFA

Parent topic:Process APIs

Home

Guides

APIs

Process Start API

Example API URLs

Request Parameters

Response Parameters

Errors

Applicable Processes

​Process Start API

​Example API URLs

​Request Parameters

​Response Parameters

​Errors

​Applicable Processes

Process Start API

Example API URLs

Request Parameters

Response Parameters

Errors

Applicable Processes