User experience

Overview

Employment history (product_type = employment) can be useful for background screening or verification of employment for lending.

Citadel's Employment History product allows you to access all user's employment information that can be found in authenticated account.

Employment history data includes information about user identity, their employer and employment status.

Use product = employment when initiating Citadel Bridge.

User flow

When deciding on where to incorporate Citadel into your user flow, we recommend taking into account the data you already have about your users.

No employment info

When you don't have data about employer, user should be able to search for their current and previous employer inside Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API..

📘

We recommend sending all users through Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. to improve ConversionConversion - the number of successful connection divided by the number of users who engaged with Citadel Bridge. rate and Pull through ratePull through rate - the number of successful connection divided by the number of users who *had an opportunity to engage* with Citadel Bridge..

Reach out to [email protected] for suggested UX and copy for employment history verification.

Successful connection

There are two options after successful login:

  1. Show successful status and let user close the BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. right after the login (takes 5-10s on average). You would need to subscribe to Webhooks or poll Citadel's backend API to check the status of the data readiness.
  2. Wait for basic employment information to be parsed and show successful status after the data becomes available (takes 30-45 seconds on average).

After successfully connecting account, we recommend showing to the user a confirmation in your application.

📘

We recommend waiting for basic employment information to be ready to present to the user so that they can see verification data before moving to the next step in application.

Unsuccessful connection

If user was not able to connect their account, best practice is to present an alternative verification method such as a form that they can fill out or allow your users to upload documents.

With employment info

When you have data about employer, you can use Search mapped companies endpoint to find company_mapping_id and skip employer search step.

📘

In case employer is not mapped we still recommend showing Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. to all users to improve conversion and pull-through rate.

Reach out to [email protected] for suggested UX and copy for employment history verification.

Successful connection

There are two options after successful login:

  1. Show successful status and let user close the Bridge right after login (takes 5-10s on average). You would need to subscribe to Webhooks or poll Citadel's backend API to check the status of the data readiness.
  2. Wait for basic employment information to be parsed and show success only after (takes 30-45 seconds on average)

After successfully connecting account, the best practice is to show to the user a confirmation in your application.

📘

We recommend to wait only for the login to succeed and the pull all the information in the background to compare with information provided by the user.

Unsuccessful connection

If user was not able to connect their account, best practice is to present an alternative verification method or allow your users to upload documents.

Orders

With Orders you can send user an email or sms notification and they can connect their account on Citadel-hosted site.

❗️

If you plan to verify more than just employment (e.g. collect personal information), we don't recommend using Orders. Users can be confused from receiving multiple emails and sms from your company.

User education

Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. is a new way to verify employment history so majority of users connect their payroll account for the first time. To increase conversion rates we recommend educating your users about Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API. by explaining benefits and setting the right context before initializing Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API..

Your application flow

Before showing Citadel BridgeBridge - The client-side component that your users will interact with in order to link their payroll accounts to Citadel and allow you to access their accounts via the Citadel API., we suggest explaining how Citadel API works step-by-step and providing user the comfort that the process is private and secure.

Users need to understand how they can benefit from connecting their account. Explaining that they can instantly complete verification instead of waiting for a few days can improve conversion rates.

For examples reach out to [email protected].

Citadel Bridge

If explaining benefits and setting context doesn't fit into your application UI, you can use "How it works tutorial". Visit White labeling section in dashboard to enable the screen in Citadel Bridge.

Multiple employments

If a user has been employed at more than one employer that uses the same payroll provider (e.g. ADP), employment history from all employers will be returned when available.


Did this page help you?