Querying people

The API distinguishes two kinds of people:

• Users — natural people who appear as administrators (board members or external administrators) of organizations on your bank. The users* queries surface only users with active memberships in your bank's organizations.
• Employees — staff at your own bank.

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

List users

query listUsers($first: Int) {
users(first: $first) {
  totalCount
  nodes {
    id
    firstname
    lastname
    email
  }
  pageInfo {
    hasNextPage
    endCursor
  }
}
}

Sortable fields: id, name. Filterable fields: id.

Get a user by ID

userById returns a list ([User!]!) — usually with zero or one element.

query getUserById($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  email
  phoneNumber
}
}

Empty list if the user has no active membership in any organization on your bank.

Get many users by ID

query getMultipleUsersByIds($userIds: [UUID!]!) {
usersById(userIds: $userIds) {
  id
  firstname
  lastname
  email
}
}

Returns a flat list with one element per matching user — IDs that don't match (or aren't visible to your bank) are simply absent.

Look up by SSN

If you only have a social security number, use usersBySsn. The server encrypts the supplied SSN before comparing it to stored encrypted values — you don't need to encrypt it yourself. Returns a flat list, usually with zero or one element.

query findUsersBySsn($ssn: String!) {
usersBySsn(ssn: $ssn) {
  id
  firstname
  lastname
  email
}
}

List your bank's employees

query listEmployees($first: Int) {
employees(first: $first) {
  totalCount
  nodes {
    id
    externalId
    firstName
    lastName
    email
    creationDate
    lastLoginTime
  }
}
}

Sortable fields: id, name. Filterable fields: id. Support employees and soft-deleted accounts are excluded automatically.

Distinguish board members from external administrators

User.administrators returns the Administrator interface. The interface has two concrete implementations — BoardMember and ExternalAdministrator — each with its own role list. Use inline fragments to project the type-specific fields, and project the __typename meta-field to discriminate the concrete type on the client without having to inspect which type-specific fields are populated.

query userAdministrators($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  administrators {
    __typename
    id
    organization {
      id
      name
      vatNumber
    }
    allowEBoksCommunicationFromBank
    ... on BoardMember {
      isAuthorizedSignatory
      boardMemberRoles {
        role
        assignedDate
        resignedDate
      }
    }
    ... on ExternalAdministrator {
      externalAdministratorRoles {
        role
        assignedDate
        resignedDate
      }
    }
  }
}
}

BoardMemberRoles includes CHAIR_MAN, CASHIER, SECRETARY, BOARD_MEMBER, …; ExternalAdministratorRoles includes CEO, ACCOUNTANT, etc. See the live schema for the full enums.

Find every organization a user administers

A common task: given a user, list every customer they have an active relationship with.

query userOrganizations($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  administrators {
    organization {
      id
      name
      vatNumber
      bankRelation {
        isAjour
        ajourDate
      }
    }
  }
}
}

Pull a user with full KYC

Users with a LegalEntity carry the KYC payload — SSN (encrypted, returned as plaintext only when authorized), legal name, place of birth, citizenships, tax residencies, and identity verifications.

query userKyc($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  email
  isExemptFromDigitalSignatures
  addressEntity {
    streetName
    houseNumberAndLetter
    postalCode
    city
    country {
      alpha2
      name
    }
  }
  legalEntity {
    id
    ssn
    legalName
    cityOrLocationOfBirth
    countryOfBirth {
      alpha2
      name
    }
    isEidVerified
    citizenships {
      countryData {
        alpha2
        name
      }
      ssn
    }
    taxResidencies {
      countryData {
        alpha2
        name
      }
      tin
    }
  }
  politicallyExposedPerson {
    pepResponse
    pepReason
  }
}
}

The flat address, country, etc. fields on User are deprecated — use addressEntity instead. Same goes for the deprecated country: String on citizenships and tax residencies — use countryData.

Identity verification details

LegalEntity.currentVerification carries the active e-id legitimation. Its riskData is the RiskData interface — for MitID-verified users, the concrete type is MitIDRiskData and exposes the device, geo, and timing data captured at verification.

The MitID file is only kept when the user logged in at authenticationLevel HIGH. For any other login file and fileId are null.

query userIdentityVerification($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  legalEntity {
    isEidVerified
    currentVerification {
      id
      identityScheme
      authenticationLevel
      identificationTime
      riskData {
        ... on MitIDRiskData {
          id
          deviceId
          registrationDateTime
          previousAuthentication
          failedAttempts
          clientGeoLocation
          clientIpAddress
          appGeoLocation
          appIpAddress
          file {
            fileName
            fileExtension
          }
        }
      }
    }
    verifications {
      id
      identityScheme
      authenticationLevel
      identificationTime
    }
  }
}
}

identityScheme is MANUAL or DK_MIT_ID. authenticationLevel is NONE / LOW / MEDIUM / HIGH.

Pull legitimation documents

PhotoLegitimation and SocialSecurityCard are the user's identity-document submissions. Both expose a state (PENDING, APPROVED, REJECTED, EXPIRED), a rejection reason if applicable, and an EncryptedBlobFile with base64 for the document itself.

query userLegitimationDocuments($userId: UUID!) {
userById(userId: $userId) {
  id
  currentPhotoLegitimation {
    state
    rejectedReason
    createdTime
    approvedRejectedTime
    expirationDate
    legitimationType {
      id
      legitimationTypeLocalizations {
        languageCode
        name
      }
    }
    file {
      fileName
      fileExtension
    }
  }
  currentSocialSecurityCard {
    state
    rejectedReason
    createdTime
    approvedRejectedTime
    expirationDate
    file {
      fileName
      fileExtension
    }
  }
}
}

Add base64 on file when you actually need the bytes — these can be large.

Look up by SSN, then expand

usersBySsn plus a single follow-up selection lets you find someone and see what they administer in one round-trip.

query usersBySsnWithRelations($ssn: String!) {
usersBySsn(ssn: $ssn) {
  id
  firstname
  lastname
  email
  legalEntity {
    legalName
    isEidVerified
  }
  administrators {
    organization {
      id
      name
      vatNumber
    }
    ... on BoardMember {
      isAuthorizedSignatory
      boardMemberRoles {
        role
      }
    }
    ... on ExternalAdministrator {
      externalAdministratorRoles {
        role
      }
    }
  }
}
}