Add one member

Add a single account membership with the API. If you use Swan's Web Banking interface, eligible account members can also invite members directly from the app.

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 the account membership

1. Call the addAccountMembership mutation.
2. Add the account ID to which you're adding an 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. Add your consentRedirectUrl (line 11).
   • Required: when granting any permissions (the API returns a validation rejection if omitted).
   • Optional: for view-only access or no permissions.
5. Choose true for the permissions you'd like to grant to the invited account member (lines 13-17).
6. Choose the account membership language (line 18). 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 21).
8. Add the consent URL to the success payload (line 30): statusInfo > AccountMembershipConsentPendingStatusInfo > consent > consentUrl.
9. Add rejections (starting on line 38).

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 AddMember {
  addAccountMembership(
    input: {
      accountId: "$ACCOUNT_ID"
      restrictedTo: {
        firstName: "Jules"
        lastName: "Fleury"
        phoneNumber: "+33600000000"
        birthDate: "yyyy-mm-dd"
      }
      consentRedirectUrl: "$REDIRECT_URL"
      email: "jules.fleury@mybrand.io"
      canInitiatePayments: true
      canManageAccountMembership: true
      canManageBeneficiaries: true
      canManageCards: false
      canViewAccount: true
      language: en
    }
  ) {
    ... on AddAccountMembershipSuccessPayload {
      __typename
      accountMembership {
        id
        statusInfo {
          status
          ... on AccountMembershipConsentPendingStatusInfo {
            __typename
            consent {
              consentUrl
              status
            }
            status
          }
        }
      }
    }
    ... on BadAccountStatusRejection {
      id
      message
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on InvalidPhoneNumberRejection {
      __typename
      message
    }
    ... on PermissionCannotBeGrantedRejection {
      __typename
      message
    }
    ... on ValidationRejection {
      __typename
      fields {
        code
        message
        path
      }
      message
    }
  }
}

Step 2: Get consent to add member

1. Get the consentUrl, included in the payload (line 11). Remember, the payload only returns the consentUrl if you added it in step 1.8.
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, 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"
      }
    }
  }
}