Person

People are a core part of the Checkmate system - the very reason Checkmate exists is so you can securely view, share and edit personal identity documents. On this page, we'll dive into the fields available on the Person model and how you can use them to create entities programatically.

The person entity

The person entity contains all the information about an individual, such as their legal identity, address, contact information and bank accounts. Each structure is individually encrypted, allowing fine-grained access and sharing. Many of the fields applicable to people are also applicable to companies, (e.g bank accounts). For details on these models you can refer to their individual docs.

Properties

  • Name
    identity
    Type
    Person.Identity
    Description

    The identity claims for the person represented by this token

  • Name
    address
    Type
    Person.ResidentialAddress
    Optional
    Optional
    Description

    The current and previous address claims of the person

  • Name
    emails
    Type
    Person.EmailAddresses
    Optional
    Optional
    Description

    Email address claims, with verification attestations.

  • Name
    phoneNumbers
    Type
    Person.PhoneNumbers
    Optional
    Optional
    Description

    Phone number claims, with verification attestations.

  • Name
    walletAddresses
    Type
    Person.WalletAddresses
    Optional
    Optional
    Description

    Wallet address claims, with verification attestations.

  • Name
    sourceOfWealth
    Type
    Person.WealthSource
    Optional
    Optional
    Description

    Evidence for the person's source of wealth

  • Name
    bankAccounts
    Type
    Person.BankAccounts
    Optional
    Optional
    Description

    List of bank accounts that the person owns

  • Name
    estate
    Type
    Person.Estate
    Optional
    Optional
    Description

    Will, power of attorney and estate plans

Creating a person

You can create a person entity directly as shown here, or you can initialise each of the fields seperately.

import { Person, FundingSourceType, WealthSourceType, BankAccountType } from '@checkmateid/sdk'

const person = new Person({
  identity: {
    name: {
      familyName: 'Griffin',
      middleName: '',
      givenName: 'Elizabeth',
    },
    otherNames: [{
      type: 'previous',
      familyName: 'Ferreira',
      middleName: '',
      givenName: 'Elizabeth',
    }],
    dateOfBirth: '1990-01-01',
    placeOfBirth: {
      country: 'GB',
    },
    nationalities: ['GB'],
  },
  address: {
    current: {
      streetAddress: '3590 Williams Avenue',
      locality: 'Los Angeles',
      region: 'California',
      postalCode: '90017',
      country: 'US',
    },
    history: [{
      streetAddress: '1600 Pennsylvania Avenue',
      locality: 'Washington, DC',
      region: '',
      postalCode: '20500',
      country: 'US',
      startDate: '2009-01-20',
      endDate: '2017-01-20',
    }]
  },
  emails: [{
    label: 'Work',
    value: 'richard@piedpiper.com',
  }],
  phoneNumbers: [{
    label: 'Work',
    value: '+16613063363',
  }],
  walletAddresses: [{
    address: '0x0c4006807b19387211f6fd07B98157FfBD8C9415',
    label: 'Trezor',
    chains: [1, 137],
  }],
  sourceOfWealth: {
    fundingSource: FundingSourceType.PersonalSavings,
    wealthSource: WealthSourceType.Investments,
  },
  bankAccounts: [{
    type: BankAccountType.SWIFT,
    iban: 'GB55REVO00996904854211',
    bic: 'REVOGB21',
    intermediaryBic: 'CHASGB2L',
  }]
})

Attaching evidence to claims

Evidence allows each of the claims about a person to be verified. Evidence must be created through the static create method, which automatically attaches file metadata.

import { Evidence, DocumentType } from '@checkmateid/sdk'

const passport = await Evidence.Document.create({
  file: passportFile,
  type: DocumentType.Passport,
  details: {
    documentNumber: '12345678',
    issuanceDate: '2010-01-01',
    expirationDate: '2017-01-01',
  }
})

const bankStatement = await Evidence.Document.create({
  file: bankStatementFile,
  type: DocumentType.BankStatement,
  details: {
    documentNumber: '12345678',
    issuanceDate: '2023-01-01',
  }
})

person.identity.addEvidence(passport)
person.address.addEvidence(bankStatement)
1

Identity

This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page.

Properties

  • Name
    name
    Type
    Name
    Field ID
    ID: 1
    Description

    Current name of the person

  • Name
    otherNames
    Type
    OtherName[]
    Optional
    Optional
    Field ID
    ID: 2
    Description

    Previous names if available

    • Name
      type
      Type
      "previous" | "alias"
      Description

      Whether this is a previous name or an alias

    • Name
      familyName
      Type
      string
      Description

      As per OpenID Connect Core 5.1

    • Name
      middleName
      Type
      string
      Optional
      Optional
      Description

      As per OpenID Connect Core 5.1

    • Name
      givenName
      Type
      string
      Description

      As per OpenID Connect Core 5.1

    • Name
      startDate
      Type
      string
      Optional
      Optional
      Description

      Date from which this name came into effect, as an ISO 8601 date

    • Name
      endDate
      Type
      string
      Optional
      Optional
      Description

      Date when this name was superseded, as an ISO 8601 date

  • Name
    dateOfBirth
    Type
    string
    Field ID
    ID: 3
    Description

    Date of birth, as an ISO 8601 date

  • Name
    placeOfBirth
    Type
    BirthPlace
    Field ID
    ID: 4
    Description

    The person's birthplace

    • Name
      country
      Type
      string
      Description

      Country of birth, as ISO 3166-1 (alpha-2) country code

    • Name
      region
      Type
      string
      Optional
      Optional
      Description

      Optional region field

    • Name
      locality
      Type
      string
      Optional
      Optional
      Description

      Optional city or locality field

  • Name
    nationalities
    Type
    string[]
    Field ID
    ID: 5
    Description

    Array of nationalities, as ISO 3166-1 (alpha-2) country codes

  • Name
    evidence
    Type
    Evidence[]
    Optional
    Optional
    Field ID
    ID: 4094
    Description

    Array of evidence objects supporting this claim. Supports the following document types:

    • Passport
    • DrivingLicense
    • NationalID
    • MilitaryID

Usage

import { Person, Evidence, DocumentType } from '@checkmateid/sdk'

const passport = await Evidence.Document.create({
  file,
  type: DocumentType.Passport,
  details: {
    documentNumber: '12345678',
    issuanceDate: '2010-01-01',
    expirationDate: '2017-01-01',
  }
})

const identity = new Person.Identity({
  name: {
    familyName: 'Griffin',
    middleName: '',
    givenName: 'Elizabeth',
  },
  otherNames: [{
    type: 'previous',
    familyName: 'Ferreira',
    middleName: '',
    givenName: 'Elizabeth',
  }],
  dateOfBirth: '1990-01-01',
  placeOfBirth: {
    country: 'GB',
  },
  nationalities: ['GB'],
  evidence: [passport],
})
2

Residential Address

Current and historical residential addresses of a person. Based on OpenID Connect Core 5.1.

  • Name
    current
    Type
    PostalAddress
    Field ID
    ID: 1
    Description

    Current residential address of the person

    • Name
      streetAddress
      Type
      string
      Description

      Full street address, including house number

    • Name
      locality
      Type
      string
      Description

      City or locality component

    • Name
      region
      Type
      string
      Optional
      Optional
      Description

      State, province, prefecture or region component

    • Name
      postalCode
      Type
      string
      Description

      ZIP code or postal code component

    • Name
      country
      Type
      string
      Description

      ISO 3166-1 (alpha-2) country code

  • Name
    history
    Type
    PostalAddressHistorical[]
    Field ID
    ID: 2
    Description

    Historical addresses, if available

    • Name
      streetAddress
      Type
      string
      Description

      Full street address, including house number

    • Name
      locality
      Type
      string
      Description

      City or locality component

    • Name
      region
      Type
      string
      Optional
      Optional
      Description

      State, province, prefecture or region component

    • Name
      postalCode
      Type
      string
      Description

      ZIP code or postal code component

    • Name
      country
      Type
      string
      Description

      ISO 3166-1 (alpha-2) country code

    • Name
      startDate
      Type
      string
      Optional
      Optional
      Description

      Start date of the persons residency, as an ISO 8601 date

    • Name
      endDate
      Type
      string
      Optional
      Optional
      Description

      End date of the persons residency, as an ISO 8601 date

  • Name
    evidence
    Type
    Evidence[]
    Optional
    Optional
    Field ID
    ID: 4094
    Description

    Array of evidence objects supporting this claim. Supports the following document types:

    • BankStatement
    • CreditCardStatement
    • UtilityBill
    • GovernmentCorrespondence
    • LeaseAgreement
    • MortgageStatement

Usage

import { Person, Evidence, DocumentType } from '@checkmateid/sdk'

const bankStatement = await Evidence.Document.create({
  file,
  type: DocumentType.BankStatement,
  details: {
    documentNumber: '12345678',
    issuanceDate: '2023-01-01',
  }
})

const address = new Person.Address({
  current: {
    streetAddress: '3590 Williams Avenue',
    locality: 'Los Angeles',
    region: 'California',
    postalCode: '90017',
    country: 'US',
  },
  history: [{
    streetAddress: '1600 Pennsylvania Avenue',
    locality: 'Washington, DC',
    region: '',
    postalCode: '20500',
    country: 'US',
    startDate: '2009-01-20',
    endDate: '2017-01-20',
  }],
  evidence: [bankStatement],
})
3

Email Addresses

Attach email addresses to a profile. You can request verification, which will send a single-use code that can be exchanged for a verification attestation signed by Checkmate.

  • Name
    value
    Type
    string
    Description

    Email address

  • Name
    label
    Type
    string
    Optional
    Optional
    Description

    Human-readable label for this email

Read the docs for the EmailAddress model

Usage

import { Person, EmailAddress } from '@checkmateid/sdk'

const workEmail = new EmailAddress({
  label: 'Work',
  value: 'richard@piedpiper.com',
})

// Request a verification code (optional)
await workEmail.requestOTP();

// Exchange verification code for an attestation
await workEmail.confirmOTP('123456');

const emails = new Person.EmailAddresses([
  workEmail,
])
4

Phone Numbers

Attach phone numbers to a profile. You can request verification, which will send a single-use code that can be exchanged for a verification attestation signed by Checkmate.

  • Name
    value
    Type
    string
    Description

    Phone number, as an E.164 string

  • Name
    label
    Type
    string
    Optional
    Optional
    Description

    Human-readable label for this phone number

Read the docs for the PhoneNumber model

Usage

import { Person, PhoneNumber } from '@checkmateid/sdk'

const workNumber = new PhoneNumber({
  label: 'Work',
  value: '+16613063363',
})

// Request a verification code (optional)
await workNumber.requestOTP();

// Exchange verification code for an attestation
await workNumber.confirmOTP('123456');

const phoneNumbers = new Person.PhoneNumbers([
  workNumber,
  // Or add an unverified phone number
  {
    label: 'Personal',
    value: '+12134706240',
  }
])
5

Wallet Addresses

Attach wallet addresses to a profile. Ownership can be verified by signing each entry with the corresponding wallet.

  • Name
    address
    Type
    string
    Description

    Wallet address

  • Name
    label
    Type
    string
    Optional
    Optional
    Description

    Human-readable label for this wallet address

  • Name
    chains
    Type
    string[]
    Optional
    Optional
    Description

    Array of chain IDs that this wallet can transact in

  • Name
    publicKey
    Type
    string
    Optional
    Optional
    Description

    Hex-encoded public key of the wallet

Read the docs for the WalletAddress model

Usage

import { Person, WalletAddress } from '@checkmateid/sdk'

const trezor = new WalletAddress({
  address: '0x0c4006807b19387211f6fd07B98157FfBD8C9415',
  label: 'Trezor',
  chains: ['1', '137'], // supports Ethereum & Polygon
})

// Request a challenge
const message = await trezor.requestChallenge()

// Sign the message, then request verification
await trezor.verifyChallengeResponse({ message, signature })

const walletAddresses = new Person.WalletAddresses([
  trezor
])
6

Wealth Source

Attach information about the person's source of wealth.

  • Name
    fundingSource
    Type
    FundingSourceType[]
    Field ID
    ID: 1
    Description

    The origins of money that the person uses to finance their operations.

    • PersonalSavings
    • Pension
    • ShareDividends
    • RealEstate
    • Gambling
    • Inheritance
    • LegalCompensation
    • EmploymentIncome
  • Name
    wealthSource
    Type
    WealthSourceType[]
    Field ID
    ID: 2
    Description

    Origins of the person's entire body of wealth (ie. total assets).

    • Inheritance
    • Investments
    • BusinessInterests
    • EmploymentIncome
  • Name
    evidence
    Type
    Evidence[]
    Optional
    Optional
    Field ID
    ID: 4094
    Description

    Array of evidence objects supporting this claim

Usage

import { Person, Evidence, DocumentType, FundingSourceType, WealthSourceType } from '@checkmateid/sdk'

const proofOfFunds = await Evidence.Document.create({
  file,
  type: DocumentType.BankStatement,
  details: {
    documentNumber: '12345678',
    issuanceDate: '2023-01-01',
  }
})

const wealthSource = new Person.WealthSource({
  fundingSource: FundingSourceType.PersonalSavings,
  wealthSource: WealthSourceType.Investments,
  evidence: [proofOfFunds],
})
7

Bank Accounts

Attach a list of bank accounts that are controlled by the person.

  • Name
    label
    Type
    string
    Optional
    Optional
    Description

    Human-readable label for the account

  • Name
    currencies
    Type
    string[]
    Optional
    Optional
    Description

    Array of ISO 4217 currency codes that this account accepts

  • Name
    beneficiary
    Type
    BankAccountBeneficiary
    Optional
    Optional
    Description

    The account beneficiary. This should usually be the same as the person's identity.

    • Name
      name
      Type
      string
      Description

      Full name of the beneficiary

    • Name
      address
      Type
      PostalAddress
      Description

      Address of the beneficiary

  • Name
    institution
    Type
    BankAccountInstitution
    Optional
    Optional
    Description

    Name and address of the bank.

    • Name
      name
      Type
      string
      Description

      Legal name of the bank

    • Name
      address
      Type
      PostalAddress
      Description

      Address of the bank

  • Name
    type
    Type
    BankAccountType
    Description

    Type of transfer supported by this account

    • FasterPayments
    • SWIFT
    • ACH
    • Wire
  • Name
    accountNumber
    Type
    string
    Description

    Account number. Required if type is FasterPayments, ACH or Wire.

  • Name
    achRoutingNumber
    Type
    string
    Description

    ACH routing number. Required if type ACH.

  • Name
    wireRoutingNumber
    Type
    string
    Description

    Wire routing number. Required if type Wire.

  • Name
    sortCode
    Type
    string
    Description

    Sort code. Required if type FasterPayments.

  • Name
    iban
    Type
    string
    Description

    IBAN (International Bank Account Number). Required if type SWIFT.

  • Name
    bic
    Type
    string
    Description

    BIC (Bank Identification Code). Required if type SWIFT.

  • Name
    intermediaryBic
    Type
    string
    Optional
    Optional
    Description

    Intermediary BIC, if required. Only used if type SWIFT.

Read the docs for the BankAccount model

Usage

import { Person, BankAccountType } from '@checkmateid/sdk'

const bankAccounts = new Person.BankAccounts([
  {
    label: 'Primary Deposit',
    currencies: ['GBP', 'USD', 'EUR'],
    beneficiary: {
      name: 'Elizabeth Griffin',
      address: {
        streetAddress: '3590 Williams Avenue',
        locality: 'Los Angeles',
        region: 'California',
        postalCode: '90017',
        country: 'US',
      }
    },
    institution: {
      name: 'Revolut Ltd',
      address: {
        streetAddress: '7 Westferry Circus',
        locality: 'London',
        region: '',
        postalCode: 'E14 4HD',
        country: 'GB',
      }
    },
    type: BankAccountType.SWIFT,
    iban: 'GB55REVO00996904854211',
    bic: 'REVOGB21',
    intermediaryBic: 'CHASGB2L',
  }
])
8

Estate

Information about the person's estate, will and power of attorney documents.

  • Name
    will
    Type
    Document
    Optional
    Optional
    Field ID
    ID: 1
    Description

    The person's will document

  • Name
    poa
    Type
    Document
    Optional
    Optional
    Field ID
    ID: 2
    Description

    Power of attorney document

  • Name
    estatePlan
    Type
    Document
    Optional
    Optional
    Field ID
    ID: 3
    Description

    Plan for the person's estate

Usage

import { Person, Document, DocumentType } from '@checkmateid/sdk'

const will = await Document.create({
  file,
  type: DocumentType.Will,
})

const poa = await Document.create({
  file,
  type: DocumentType.POA,
})

const estatePlan = await Document.create({
  file,
  type: DocumentType.EstatePlan,
})

const estate = new Person.Estate({
  will,
  poa,
  estatePlan,
})

Was this page helpful?