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 of the account where you're inviting members (line 4).
3. Add your consentRedirectUrl (line 5).
   • Required: if any member receives any permissions (the API returns a validation rejection if omitted).
   • Optional: if all members have view-only access or no permissions.
4. Add one invited account member block for each invitee (lines 7-21).
5. 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.
6. Choose true for the permissions you'd like to grant to the invited account member.
7. Choose the account membership language (line 20). If no language is chosen, the membership inherits the account language.
8. Add the success payload, including any information you'd like to review (line 55).
9. Add the consent URL to the success payload (line 63): statusInfo > AccountMembershipConsentPendingStatusInfo > consent > consentUrl.
10. Add rejections (starting on line 70).

Can manage cards

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

Open 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
          }
        }
      }
    }
    ... on BadAccountStatusRejection {
      id
      message
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on InvalidPhoneNumberRejection {
      __typename
      message
    }
    ... on PermissionCannotBeGrantedRejection {
      __typename
      message
    }
    ... on TooManyItemsRejection {
      __typename
      message
    }
    ... on ValidationRejection {
      __typename
      fields {
        code
        message
        path
      }
      message
    }
  }
}

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 (line 11).
   • All consent URLs are the same when adding members in bulk.
   • Remember, the payload only returns the consentUrl if you added it in step 1.9.
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, such as the membership not being found (line 14), the membership not being ready to be bound (line 17), or the user already being bound to a membership (line 20).
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. But 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, follow the guide to fix a user binding error.

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