Organization invitations

An organization invitation represents a prospective customer that hasn't yet completed onboarding. You create the invitation, optionally update its information, then start the invitation flow which sends the invitation to the contact person and tracks the onboarding state.

All mutations on this page require a JWT — get one from the homepage first.

Create an invitation

Creates a new invitation with contact person, bank account(s), risk group, and optional branch office. The invitation is created in a draft state — call startInvitationFlow to send it.

The input takes a nested contactPerson object, but the resulting OrganizationInvitation exposes the same data as flat chairman* fields.

mutation createOrganizationInvitation($input: CreateOrganizationInvitationInput!) {
createOrganizationInvitation(input: $input) {
  organizationInvitation {
    id
    organizationName
    vatNumber
    externalId
    chairmanFirstName
    chairmanLastName
    chairmanEmail
  }
}
}

Validation rules:

• bankAccounts is optional — you can create an invitation with no bank accounts and add them later via the bank UI, or leave the customer to add them post-acceptance.
• For each bank-account entry you do include, registrationNumber must be exactly 4 characters and accountNumber must be exactly 10. The two fields are validated together — you cannot provide one without the other. If you don't have an account number yet, omit the entire entry rather than half-filling it.
• isPrimary is optional. If you omit it on every account, the first account is auto-promoted to primary. At most one account may have isPrimary: true.
• The riskGroupId must reference a risk group on your bank.

Update invitation information

Updates one or more invitation fields. All fields except invitationId are optional — only the fields you provide are changed.

mutation updateOrganizationInvitationInformation($input: UpdateOrganizationInvitationInformationInput!) {
updateOrganizationInvitationInformation(input: $input) {
  organizationInvitation {
    id
    organizationName
    vatNumber
    externalId
    chairmanFirstName
    chairmanLastName
    chairmanEmail
    chairmanCallingCode
    chairmanPhoneNumber
  }
}
}

Inside contactPerson, every field is independently optional — set the ones you want to change and leave the rest as null. Pass contactPerson: null to leave the contact untouched entirely.

Set or change the branch office

Associates a branch office with the invitation. The input is doubly nested: the outer UpdateOrganizationInvitationBranchOfficeRelationInput wraps a single input: UpdateOrganizationInvitationBranchOfficeInput field. The payload also has an inner organizationInvitationPayload wrapper.

To remove the relation, pass branchOfficeId: null.

mutation updateOrganizationInvitationBranchOfficeRelation($input: UpdateOrganizationInvitationBranchOfficeRelationInput!) {
updateOrganizationInvitationBranchOfficeRelation(input: $input) {
  organizationInvitationPayload {
    organizationInvitation {
      id
      branchOffice {
        id
        name
      }
    }
  }
}
}

Start the invitation flow

Sends the invitation and starts onboarding. The response includes counters showing how many invitations you have left in the current month and week — your bank has a configured limit on both.

mutation startInvitationFlow($input: StartInvitationFlowInput!) {
startInvitationFlow(input: $input) {
  organizationInvitation {
    id
    isInvitationFlowStarted
  }
  invitationsLeft {
    invitationsPerMonth
    invitationsLast30Days
    invitationsLeftThisMonth
    invitationsPerWeek
    invitationsThisWeek
    invitationsLeftThisWeek
  }
}
}

Errors to expect:

• No more invitations left this month. used X of Y — you've hit the monthly cap.
• No more invitations left this week. used X of Y — weekly cap.
• The mutation may also return validation errors on the invitation itself (e.g. missing required information) without throwing — check the GraphQL errors array.

Delete an invitation

Soft-deletes the invitation and cancels any background jobs scheduled for it.

mutation deleteOrganizationInvitation($input: DeleteOrganizationInvitationInput!) {
deleteOrganizationInvitation(input: $input) {
  success
}
}