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
    chairmanFirstName
    chairmanLastName
    chairmanEmail
    chairmanCallingCode
    chairmanPhoneNumber
  }
}
}

Only the fields you provide are changed — leave the rest as null. The same applies inside contactPerson: any of firstName, lastName, email, callingCode, phoneNumber can be set individually. Pass contactPerson: null to leave the contact untouched entirely.

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.