Brands

A brand is a white-label identity for the Health Wallet: the name, logos, colors and emails that an Organization's members see. Every Organization and Organization Group is placed on one of your brands when you create it.

If you have one brand, you do not need to do anything: leave out brand, and everything you create uses it. If you have more than one brand, choose one each time you create an Organization or an Organization Group.

List your brands

Call the brands query:

query Brands {
    brands {
        ... on BrandsResults {
            nodes {
                name
                displayName
                isDefault
            }
        }
        ... on InternalServerError {
            code
            message
        }
    }
}

Each PartnerBrand has:

• name: the identifier. Pass this value as brand.
• displayName: a display name in the request language, or null if none is set. It is not unique, so do not use it to identify a brand.
• isDefault: true for your default brand. The default brand applies only when you have one brand. If you have more than one brand, leaving out brand does not use the default, and the call can fail with AMBIGUOUS_SHARD. See Errors.

To read one brand, call brand with its name. The name must match exactly, including case. A name that is not one of your brands returns BadRequestError with code: NOT_FOUND.

query Brand($where: BrandFilterInput!) {
    brand(where: $where) {
        ... on PartnerBrand {
            name
            displayName
            isDefault
        }
        ... on BadRequestError {
            code
            message
        }
        ... on InternalServerError {
            code
            message
        }
    }
}

{
    "where": { "name": "<brand name>" }
}

Choose a brand for an Organization

Pass brand on createOrganization. A brand can be available on more than one of your banks. In that case, also pass bank: the bank ID First Dollar gave you, or one listed in extensions.custodians on an AMBIGUOUS_SHARD error. bank is an ID. If your query document writes the value inline, quote it (bank: "G"); a value passed through variables needs no change. See Breaking Changes.

mutation CreateOrganization($input: CreateOrganizationInput!) {
    createOrganization(input: $input) {
        ... on CreateOrganizationResult {
            organization {
                id
                name
            }
        }
        ... on BadRequestError {
            code
            message
        }
        ... on InternalServerError {
            code
            message
        }
    }
}

{
    "input": {
        "name": "Acme East",
        "brand": "<brand name>"
    }
}

How createOrganization places the Organization:

You pass	Result
Neither brand nor bank	If you have one brand, the Organization uses it. If you have more than one brand, the call fails with AMBIGUOUS_SHARD.
brand	The Organization uses that brand. If the brand is available on more than one bank, the call fails with AMBIGUOUS_SHARD and asks for bank.
brand and bank	The Organization uses that brand on that bank.
bank	The Organization uses the one brand that you have on that bank. If you have more than one brand on it, the call fails with AMBIGUOUS_SHARD and asks for brand.

Choose a brand for an Organization Group

createOrganizationGroup takes the same brand and bank inputs, with the same results when you pass them. When you leave out both, the Organization Group is placed on the bank that your API credentials belong to. If you have more than one brand on that bank, the call fails with AMBIGUOUS_SHARD.

An Organization does not take its brand from its Organization Group. Pass brand on each createOrganization call too.

Errors

Placement failures are top-level GraphQL errors with HTTP status 422, not BadRequestError results. Read extensions.code:

• AMBIGUOUS_SHARD: the request needs one more value. extensions.requiredKey names the field to add (brand or bank). extensions.brands or extensions.custodians lists the values that you can choose from.
• NO_SHARD_PROVISIONED: the brand, the bank, or the combination is not available to you. Check brand against the brands query and bank against the IDs First Dollar gave you.

A bank value that is not a bank ID at all fails earlier, as a top-level BAD_USER_INPUT error with HTTP status 200. extensions.custodians lists every accepted ID.

After creation

• You cannot change an Organization's or an Organization Group's brand through the Partner API. To move an Organization to another brand, contact [email protected].
• Divisions always use their parent Organization's brand. createDivision has no brand input.