Account, consent, and identity

Capture the user's profile, record their consents, and verify their identity from the assistant

Set up the user's b.well account from the chat. The assistant fills in the demographics b.well uses to link the user's health records to their account, records the consents your use case requires, and starts identity verification, which Smart Connect and some data sources require.

Before you start

These tools are optional. If users complete these steps in your web app or through the b.well SDKs, leave them out of your assistant. Account, Consent & Identity documents each tool.

The server confirms update_user_profile and create_consent with the user; see MCP server reference. Because initiate_identity_verification starts a live verification session right away, configure your host to ask the user before it runs, or ask in your application if your host has no approval setting.

Account creation and consent

A new user needs baseline demographics, such as name and birth date, before b.well can link health records to their account. When your account integration doesn't supply them, or the user wants to change them, the assistant captures them in the chat.

  1. Call get_user_profile to read what b.well has on file.
  2. Call update_user_profile with only the fields the user gives or changes. Omitted fields keep their values. telecom replaces the whole list, so to add a phone number, send the existing entries plus the new one. address takes one address and replaces the one on file.
  3. Call list_consents with the category you need, such as TOS for the Terms of Service.
  4. Call create_consent with that category and permit set to the user's decision (true or false). The tool's inputSchema lists every category. Show the user the exact category and the permit or deny decision before the call.

The consent for a Smart Connect search has its own tool, covered in Search, connect, and manage data connections.

Identity verification

b.well verifies identity to identity assurance level 2 (IAL2) through CLEAR, a Kantara-certified credential service provider (CSP). Data sources whose integration_type is IAL2 require it before they connect. The user completes verification on CLEAR's hosted pages in their browser, outside the model's context, and a model can't complete it for them.

  1. Call get_verification_status.
  2. Call initiate_identity_verification. Leave include_attribute_matching_check at its default, false, unless your verification policy also requires the user's demographics to match their b.well profile.
  3. Your host opens the returned verification_url in a browser or webview.
  4. When the user returns, call get_verification_status again.

Guide the model

These points add to the base guidance. Use them if your host accepts your own instructions, and adapt them to your use case. They reinforce the tool descriptions and don't replace them.

  • When a new user starts, read the profile with get_user_profile, ask only for missing fields, and show the values before update_user_profile.
  • Check list_consents for the consent categories your use case needs, such as the Terms of Service (TOS). Present the document, and call create_consent only after the user answers.
  • Record only consent the user gives explicitly in this conversation, never an earlier, unrelated "yes".
  • Before connecting a data source that requires identity verification, or before a Smart Connect search, check get_verification_status. If the user isn't verified, explain why, call initiate_identity_verification, and ask the user to open the link.
  • When the user returns from verification, check get_verification_status again, because the outcome happens outside the conversation.

Handle each outcome

ResultWhat it meansWhat the model does
Error -32301 with data.missing_fieldsYour client requires onboarding, and required demographics are missingAsk for the fields data.missing_fields names, then call update_user_profile
The list_consents result is No consents found.The user hasn't decided yetPresent the document and wait for an explicit answer
Error -32302The server denied the call. When data.reason is terms_not_accepted, the user hasn't accepted the Terms of Service and Privacy Policy your client requiresTell the user, and point them to where your product collects that acceptance
verification_status.status is validatedThe user is already verifiedSkip verification
verification_status.error_code is setVerification failedTell the user what verification_status.failure_action.text says they can do next

Did this page help you?