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 adding a invited account member (line 4) and your consentRedirectUrl (line 5).
3. Add one invited account member block for each invitee (lines 7-20).
4. In each restrictedTo object, 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. Add the success payload, including any information you'd like to review (line 51).
7. Add the consent URL to the success payload (line 59): statusInfo > AccountMembershipConsentPendingStatusInfo > consent > consentUrl.
8. 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: "$YOUR_ACCOUNT_ID"
      consentRedirectUrl: "https://docs.swan.io/"
      memberships: [
        {
          email: "alberto@mybrand.io"
          restrictedTo: {
            firstName: "Alberto"
            lastName: "Romeno"
            birthDate: "1980-02-20"
            phoneNumber: "+33600000000"
          }
          canViewAccount: true
          canManageBeneficiaries: true
          canInitiatePayments: true
          canManageAccountMembership: true
          canManageCards: false
        }
        {
          email: "sofia@mybrand.io"
          restrictedTo: {
            firstName: "Sofia"
            lastName: "Ramirez"
            phoneNumber: "+33600000000"
          }
          canViewAccount: true
          canManageBeneficiaries: false
          canInitiatePayments: false
          canManageAccountMembership: false
          canManageCards: false
        }
        {
          email: "rae@mybrand.io"
          restrictedTo: {
            firstName: "Rae"
            lastName: "Schmidt"
            birthDate: "1986-09-02"
            phoneNumber: "+33600000000"
          }
          canViewAccount: true
          canManageBeneficiaries: true
          canInitiatePayments: true
          canManageAccountMembership: true
          canManageCards: true
        }
      ]
    }
  ) {
    ... on AddAccountMembershipsSuccessPayload {
      __typename
      accountMemberships {
        id
        statusInfo {
          ... on AccountMembershipConsentPendingStatusInfo {
            __typename
            consent {
              consentUrl
            }
            status
          }
        }
      }
    }
  }
}

Step 2: Get consent to add member

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.

Binding error

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

🔎 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"
      }
    }
  }
}