Onboard a new customer

End-to-end: from looking up the IDs you need, through creating an invitation, sending it to the customer, and verifying the invitation is in flight.

All steps require a JWT — get one from the homepage first.

1. Find a risk group ID

Creating an invitation requires a riskGroupId — pick one your bank already has configured.

query findRiskGroups {
riskGroups(first: 50) {
  nodes {
    id
    name
  }
}
}

Copy the id of the risk classification that fits the prospective customer.

2. (Optional) Find a branch office ID

If your bank scopes customers to branch offices, look one up. Skip this if you onboard centrally.

query findBranchOffices {
branchOffices(first: 50) {
  nodes {
    id
    name
  }
}
}

3. Create the invitation

Now create the invitation in a draft state. The customer is not notified yet — that happens in step 5.

mutation createOrganizationInvitation($input: CreateOrganizationInvitationInput!) {
createOrganizationInvitation(input: $input) {
  organizationInvitation {
    id
    organizationName
    externalId
  }
}
}

Save the returned organizationInvitation.id — you'll need it for the next steps.

4. (Optional) Adjust the invitation before sending

Mistake in the contact email? Wrong VAT number? Update the draft before sending.

mutation updateInvitationInformation($input: UpdateOrganizationInvitationInformationInput!) {
updateOrganizationInvitationInformation(input: $input) {
  organizationInvitation {
    id
    organizationName
    vatNumber
  }
}
}

Only the fields you provide are changed — leave the rest as null.

5. Send it

startInvitationFlow sends the invitation email and starts onboarding. The response includes your remaining invitation quota for the month and week.

mutation sendInvitation($input: StartInvitationFlowInput!) {
startInvitationFlow(input: $input) {
  organizationInvitation {
    id
  }
  invitationsLeft {
    invitationsLeftThisMonth
    invitationsLeftThisWeek
  }
}
}

If you hit No more invitations left this month/week, you've exceeded your bank's configured cap — wait or contact Unioo to raise the limit. The mutation may also return GraphQL errors describing missing required information on the invitation itself, without throwing — always check the errors field.

Once the customer accepts the invitation, the resulting record moves from organizationInvitations to organizations — see Querying organizations.