Account Creation & Consent

When a user authenticates for the first time, b.well automatically creates their account using demographics provided in the ID token. This guide covers the post-authentication steps to complete user profile data and manage consent records. This workflow combines user profile management and consent registration through GraphQL operations.

Use these operations to:

Verify what demographic data b.well already has
Update any missing required or recommended fields
Create and manage user consent records

Prerequisites

End-User Authentication - User must be authenticated before account creation (Example: OAuth Token Exchange)

Environment URL:

Client-Sandbox: https://api.client-sandbox.icanbwell.com/v1/graphql

Workflow Steps

Step 1: Retrieve User Profile Data

Query the user's existing demographics to confirm what data is already available.

GraphQL Query:

query getProfile {
  userProfile {
    id
    address {
      line
      city
      state
      postalCode
    }
    telecom {
      system
      value
      use
    }
    gender
    birthDate
    name {
      family
      given
    }
    language
  }
}

Step 2: Update User Profile Data

Update the user’s profile (FHIR Person record) with at least the minimum required demographics.

The following fields are required to create a user profile in b.well:

Field	Type	Required	Description
`name.given`	String	Yes	First Name
`name.family`	String	Yes	Last Name
`birthDate`	String	Yes	Date of Birth (YYYY-MM-DD format

For a full list of required and recommended demographics, please refer to the User Profile Requirements page.

GraphQL Mutation:

mutation updateUserProfile($person: FHIRPersonInput) {
  updateUserProfile(input: $person) {
    id
    resourceType
    name {
      family
      given
    }
    telecom {
      system
      value
      use
    }
    gender
    birthDate
    address {
      line
      city
      state
      postalCode
    }
  }
}

Step 3: Create Consent Record

Create a consent record to register user consent for terms of service, data sharing, or other consent categories.

GraphQL Mutation:

mutation createConsent($consentInput: ConsentInput!) {
  createConsent(consentInput: $consentInput) {
    id
    provision {
      type
    }
    category {
      coding {
        code
      }
    }
    status
    patient {
      resource {
        id
      }
    }
  }
}

Available Enum Values:

Field	Available Values
Category	`TOS` `PROA_ATTESTATION` `DATA_SHARING` `COMMUNICATION_PREFERENCES_PHI` `IAS_IMPORT_RECORDS`
Status	`DRAFT` `PROPOSED` `ACTIVE` `REJECTED` `INACTIVE` `ENTERED_IN_ERROR`
Provision	`PERMIT` `DENY`

Example Variables:

{
  "consentInput": {
    "category": [
      {
        "coding": [
          {
            "system": "http://www.icanbwell.com/consent-category",
            "code": "TOS"
          }
        ]
      }
    ],
    "provision": {
      "type": "PERMIT"
    },
    "status": "ACTIVE"
  }
}

Example Response:

{
  "data": {
    "createConsent": {
      "id": "4b56d8a7-4f24-46f8-918b-34fdfe432976",
      "provision": {
        "type": "PERMIT"
      },
      "category": [
        {
          "coding": [
            {
              "code": "tos"
            }
          ]
        }
      ],
      "status": "active",
      "patient": {
        "resource": {
          "id": "a600e122-04b2-59e0-b922-d2e09afbf2d2"
        }
      }
    }
  }
}

Step 4: Retrieve User Consent Records

Query existing consent records to verify consent status or retrieve multiple consent categories.

GraphQL Query:

query getConsents($categoryCode: SearchToken, $status: SearchToken) {
  consents(category: $categoryCode, status: $status) {
    entry {
      resource {
        id
        provision {
          type
        }
        resourceType
        status
        category {
          coding {
            code
          }
        }
        dateTime
      }
    }
  }
}

Example Variables:

{
  "categoryCode": { 
    "value": {
      "code": "tos"
    }
  },
  "status": {
    "value": {
      "code": "active"
    }
  }
}

Example Response:

{
  "data": {
    "consents": {
      "entry": [
        {
          "resource": {
            "id": "e7e04a05-34d6-42cb-a479-97e041face9c",
            "provision": {
              "type": "permit"
            },
            "resourceType": "Consent",
            "status": "active",
            "category": [
              {
                "coding": [
                  {
                    "code": "59284-0"
                  }
                ]
              },
              {
                "coding": [
                  {
                    "code": "tos"
                  }
                ]
              }
            ],
            "dateTime": "2025-11-07T19:57:15.914Z"
          }
        }
      ]
    }
  }
}