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.
- Call
get_user_profileto read what b.well has on file. - Call
update_user_profilewith only the fields the user gives or changes. Omitted fields keep their values.telecomreplaces the whole list, so to add a phone number, send the existing entries plus the new one.addresstakes one address and replaces the one on file. - Call
list_consentswith thecategoryyou need, such asTOSfor the Terms of Service. - Call
create_consentwith thatcategoryandpermitset to the user's decision (trueorfalse). The tool'sinputSchemalists 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.
- Call
get_verification_status. - Call
initiate_identity_verification. Leaveinclude_attribute_matching_checkat its default,false, unless your verification policy also requires the user's demographics to match their b.well profile. - Your host opens the returned
verification_urlin a browser or webview. - When the user returns, call
get_verification_statusagain.
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 beforeupdate_user_profile. - Check
list_consentsfor the consent categories your use case needs, such as the Terms of Service (TOS). Present the document, and callcreate_consentonly 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, callinitiate_identity_verification, and ask the user to open the link. - When the user returns from verification, check
get_verification_statusagain, because the outcome happens outside the conversation.
Handle each outcome
| Result | What it means | What the model does |
|---|---|---|
Error -32301 with data.missing_fields | Your client requires onboarding, and required demographics are missing | Ask 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 yet | Present the document and wait for an explicit answer |
Error -32302 | The 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 requires | Tell the user, and point them to where your product collects that acceptance |
verification_status.status is validated | The user is already verified | Skip verification |
verification_status.error_code is set | Verification failed | Tell the user what verification_status.failure_action.text says they can do next |
Updated about 17 hours ago

