Skip to main content

Add multiple memberships

Add multiple account memberships with the API. You can add up to 200 memberships in a single API call.

Prerequisites

To add new members, you must authenticate with a user access token associated with an existing account member with the permission canManageAccountMembership.

Only account members with the permission canManageAccountMembership can add account members.

Step 1: Add account memberships​

  1. Call the addAccountMemberships mutation.
  2. Add the account ID to which you're inviting account members (line 4) and your consentRedirectUrl (line 5).
  3. Add one invited account member block for each invitee (lines 7-21).
  4. In each restrictedTo object (lines 9-14), add information about the invited account members.
    • If you're only granting canViewAccount permissions, or you're not granting any permissions, the invited account member's birthDate isn't required.
    • Include a + in front of the phone number.
  5. Choose true for the permissions you'd like to grant to the invited account member.
  6. Choose the account membership language (line 20). If no language is chosen, the membership inherits the account language.
  7. Add the success payload, including any information you'd like to review (line 51).
  8. Add the consent URL to the success payload (line 59): statusInfo > AccountMembershipConsentPendingStatusInfo > consent > consentUrl.
  9. Add rejections (not shown).
Can Manage Cards

The CanManageCards permissions is technically optional. However, it's recommended to choose true or false for this permission anyway. If you don't include the CanManageCards permission in your API call, it inherits the same value as canManageAccountMembership.

🔎 Open the mutation in API Explorer

mutation AddMultipleMembers {
  addAccountMemberships(
    input: {
      accountId: "$ACCOUNT_ID"
      consentRedirectUrl: "$REDIRECT_URL"
      memberships: [
        {
          email: "alberto@mybrand.io"
          restrictedTo: {
            firstName: "Alberto"
            lastName: "Romeno"
            phoneNumber: "+33600000000"
            birthDate: "yyyy-mm-dd"
          }
          canViewAccount: true
          canManageBeneficiaries: false
          canInitiatePayments: true
          canManageAccountMembership: false
          canManageCards: false
          language: es
        }
        {
          email: "sofia@mybrand.io"
          restrictedTo: {
            firstName: "Sofia"
            lastName: "Ramirez"
            phoneNumber: "+33600000000"
            birthDate: "yyyy-mm-dd"
          }
          canViewAccount: true
          canManageBeneficiaries: true
          canInitiatePayments: true
          canManageAccountMembership: true
          canManageCards: false
          language: es
        }
        {
          email: "rae@mybrand.io"
          restrictedTo: {
            firstName: "Rae"
            lastName: "Schmidt"
            phoneNumber: "+33600000000"
            birthDate: "yyyy-mm-dd"
          }
          canViewAccount: true
          canManageBeneficiaries: true
          canInitiatePayments: true
          canManageAccountMembership: true
          canManageCards: true
          language: de
        }
      ]
    }
  ) {
    ... on AddAccountMembershipsSuccessPayload {
      __typename
      accountMemberships {
        id
        statusInfo {
          ... on AccountMembershipConsentPendingStatusInfo {
            __typename
            consent {
              consentUrl
            }
            status
          }
        }
      }
    }
  }
}

The account holder, legal representative of the account, or account member with canManageAccountMembership permissions consents to adding all of the invited account members with a single consent process.

  1. Get the consentUrl, included in the payload (lines 11).
    • All consent URLs are the same when adding members in bulk.
    • Remember, the payload only provides the consentUrl if you added it in step 1.7.
  2. Send the consentUrl to the account holder, the account's legal representative, or the account member with canManageAccountMembership permissions.
  3. As soon as consent is provided, they're redirected to your consentRedirectUrl defined in the initial API call, which fetches an OAuth 2.0 authorization code and a user access token.
  4. Store the invited account member's new accountMembershipId. You'll need it to bind the membership.
{
  "data": {
    "addAccountMemberships": {
      "__typename": "AddAccountMembershipsSuccessPayload",
      "accountMemberships": [
        {
          "id": "$ACCOUNT_MEMBERSHIP_ID_ALBERTO",
          "statusInfo": {
            "__typename": "AccountMembershipConsentPendingStatusInfo",
            "consent": {
              "consentUrl": "https://identity.swan.io/consent?consentId=$CONSENT_ID&env=Sandbox"
            },
            "status": "ConsentPending"
          }
        },
        {
          "id": "$ACCOUNT_MEMBERSHIP_ID_SOFIA",
          "statusInfo": {
            "__typename": "AccountMembershipConsentPendingStatusInfo",
            "consent": {
              "consentUrl": "https://identity.swan.io/consent?consentId=$CONSENT_ID&env=Sandbox"
            },
            "status": "ConsentPending"
          }
        },
        {
          "id": "$ACCOUNT_MEMBERSHIP_ID_RAE",
          "statusInfo": {
            "__typename": "AccountMembershipConsentPendingStatusInfo",
            "consent": {
              "consentUrl": "https://identity.swan.io/consent?consentId=$CONSENT_ID&env=Sandbox"
            },
            "status": "ConsentPending"
          }
        }
      ]
    }
  }
}

Step 3: Bind the invited account member​

Bind the invited account member to their account membership.

  1. Ask the invited account member to log into Swan. They'll be asked to create a passcode.
  2. With the invited account member's user access token, call the BindAccountMembership mutation.
  3. Add the accountMembershipId for the invited account member.
  4. Add as much information to the payload as you need. Consider including several rejections, including the unions for a binding error (line 15), consent status (line 29), and if the member is already bound (line 42).
  5. If the information provided by the invited account member matches what you provided, the account member's membership status changes to Enabled and they can start using the account according to their permissions.
Update membership language

You can update the account membership language when binding the account member by including it in the accept-language header. However, this isn't the recommended method. It's best to choose the language when adding the membership (step 1 of this page), or to update the membership.

Binding error

If the API returns a user binding error, please follow the guide to fix it.

🔎 Open the mutation in API Explorer

mutation BindMember {
  bindAccountMembership(
    input: { accountMembershipId: "$YOUR_MEMBERSHIP_ID" }
  ) {
    ... on BindAccountMembershipSuccessPayload {
      __typename
      accountMembership {
        id
      }
    }
    ... on BadAccountStatusRejection {
      id
    }
    ... on AccountMembershipNotFoundRejection {
      id
    }
    ... on AccountMembershipNotReadyToBeBoundRejection {
      id
    }
    ... on IdentityAlreadyBindToAccountMembershipRejection {
      __typename
    }
    ... on RestrictedToUserRejection {
      __typename
    }
    ... on ValidationRejection {
      __typename
    }
  }
}
Payload
{
  "data": {
    "bindAccountMembership": {
      "__typename": "BindAccountMembershipSuccessPayload",
      "accountMembership": {
        "id": "$YOUR_MEMBERSHIP_ID"
      }
    }
  }
}