Skip to main content

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
    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.

query userAdministrators($userId: UUID!) {
userById(userId: $userId) {
  id
  firstname
  lastname
  administrators {
    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.

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
      }
    }
  }
}
}