Add a membership

Add a single account membership with the API or from Swan's Web Banking interface.

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.

API guide

Step 1: Add the account membership

1. Call the addAccountMembership mutation.
2. Add the account ID to which you're adding a invited account member (line 4).
3. In the restrictedTo object, add information about the invited account member (lines 6-9).
   • 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.
4. Choose true for the permissions you'd like to grant to the invited account member (lines 13-17).
5. Add the success payload, including any information you'd like to review (line 20).
6. Add the consent URL to the success payload (line 29): statusInfo > AccountMembershipConsentPendingStatusInfo > consent > consentUrl.
7. 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 AddMember {
  addAccountMembership(
    input: {
      accountId: "$YOUR_ACCOUNT_ID"
      restrictedTo: {
        firstName: "Jules"
        lastName: "Fleury"
        phoneNumber: "+33600000000"
        birthDate: "1992-04-23"
      }
      consentRedirectUrl: "https://docs.swan.io/"
      email: "jules.fleury@mybrand.io"
      canInitiatePayments: true
      canManageAccountMembership: false
      canManageBeneficiaries: true
      canManageCards: false
      canViewAccount: true
    }
  ) {
    ... on AddAccountMembershipSuccessPayload {
      __typename
      accountMembership {
        id
        statusInfo {
          status
          ... on AccountMembershipConsentPendingStatusInfo {
            __typename
            consent {
              consentUrl
              status
            }
            status
          }
        }
      }
    }
  }
}

Step 2: Get consent to add member

1. Get the consentUrl, included in the payload (line 11). Remember, the payload only provides the consentUrl if you added it in step 1.6.
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": {
    "addAccountMembership": {
      "__typename": "AddAccountMembershipSuccessPayload",
      "accountMembership": {
        "id": "$NEW_ACCOUNT_MEMBERSHIP_ID",
        "statusInfo": {
          "status": "ConsentPending",
          "__typename": "AccountMembershipConsentPendingStatusInfo",
          "consent": {
            "consentUrl": "https://identity.swan.io/consent?consentId=$CONSENT_ID&env=Sandbox",
            "status": "Created"
          }
        }
      }
    }
  }
}

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

Web Banking guide

1. Go to Web Banking > Members, and click + New.

2. Enter information about the account member you're inviting.
3. Choose their membership permissions.
4. Click Send invitation.