Personhood

Personhood

Personhood endpoints are very simple. It consists of a few endpoints to control the sessions of your applications.

POST/v1/personhood/init

Init a new session

This endpoint allows you to initalize a new session for a given user. You should store the session_id in your database.

Request

POST
/v1/personhood/init
curl --location --request POST 'https://api.pop.anima.io/v1/personhood/init' \
--header 'Api-Key: {YOUR_API_KEY}'

Response

{
    "session_id": "f0eb93a4-f086-4f9a-803b-2b61892d4292"
}
GET/v1/sessions/{SESSION_ID}/details

Session Details

This endpoint allows you to retrieve the current state of a personhood session. It requires authentication, as it displays sensitive information such as the list of sessions that were flagged as duplicates.

Response

session - Session Object

  • Name
    state
    Type
    string
    Description

    Current state of onboarding
    APPROVED - User is approved based to your app criterias
    IN_PROGRESS - User is still doing the onboarding
    REJECTED - User is rejected based on your app criterias\

  • Name
    info
    Type
    string
    Description

    More info about the current state of onboarding\

    • for APPROVED
      OK - All good.

    • for IN_PROGRESS
      WF_LIVENESS - Waiting user to do the Liveness check
      WF_SHARE - Waiting user to do share the PoP stored in its wallet
      WF_DECENTRALIZE - Waiting user to decentralize its PoP (optional but mandatory in case you enforced decentralization through wallet)

    • for - REJECTED - User is rejected based on your app criterias
      NOT_HUMAN - Liveness provider were not able to prove user's liveliness FOUND_DUPLICATE - User already registered with another account

app - App Object

  • Name
    name
    Type
    string
    Description

    App name

  • Name
    logo_url
    Type
    string
    Description

    URL to registered app logo

  • Name
    duplicate
    Type
    boolean
    Description

    true if duplicate checks has been enabled
    false if only liveness check has been enabled

  • Name
    force_wallet
    Type
    boolean
    Description

    true if a wallet is required either through PoP sharing or PoP decentralization
    false if a wallet is optional

verifier - Verifier Object
Learn more about Anima Verifiers

  • Name
    id
    Type
    string
    Description

    Anima Verifier ID

  • Name
    public_address
    Type
    string
    Description

    Anima Verifier Public Address

  • Name
    chain
    Type
    string
    Description

    Anima Verifier Main Chain Identifier

issuer - Issuer Object
Learn more about Anima Issuers

  • Name
    id
    Type
    string
    Description

    Anima Issuer ID

  • Name
    public_address
    Type
    string
    Description

    Anima Issuer Public Address

  • Name
    chain
    Type
    string
    Description

    Anima Issuer Main Chain Identifier

user - User Object

  • Name
    anima
    Type
    boolean
    Description

    true if user goes through Anima PoP to verify its identity (must be true if you enforced wallet creation)
    false if you did not enforced wallet

  • Name
    wallet
    Type
    string
    Description

    User's wallet address

facegraph - Facegraph Object

  • Name
    hash
    Type
    string
    Description

    When Liveness check is successful, the facegraph hash will be available to sign to allows user's PoP decentralization

duplicates - Duplicate Array

  • Name
    session_id
    Type
    string
    Description

    Session ID of a duplicate session

  • Name
    wallet
    Type
    string
    Description

    Wallet address of a duplicate session

Request

GET
/v1/sessions/{SESSION_ID}/details
  curl --location --request GET 'https://api.pop.anima.io/v1/sessions/{SESSION_ID}/details' \
  --header 'Api-Key: {YOUR_API_KEY}'

Response

{
  "session": {
      "state": "REJECTED",
      "info": "FOUND_DUPLICATE"
  },
  "app": {
      "name": "Your app name",
      "logo_url": "logo.jpg",
      "verify": true,
      "force_wallet": true
  },
  "verifier": {
      "id": "anima:verifier:[email protected]",
      "public_address": "0x684ac6ce9fd2e3a6ffab4f0debe5b529f4421a22",
      "chain": "ETH"
  },
  "issuer": {
      "id": "anima:issuer:[email protected]",
      "public_address": "0xBe053D9BaC9Dc64E32E150eddd737c8434e304c6",
      "chain": "ETH"
  },
  "user": {
      "anima": false,
      "wallet": ""
  },
  "facegraph": {
      "hash": "",
      "id": ""
  },
  "duplicates": [
    {
      "session_id": "f0eb93a4-f086-4f9a-803b-2b61892d4292",
      "wallet": "0x684ac6ce9fd2e3a6ffab4f0debe5b529f4421a22"
    }
  ]
}
POST/v1/sessions/{SESSION_ID}/unenroll

Unenroll Session

This endpoint allows you to unenroll a session from the sessions that are checked for duplicate. It allows you to permit a person to register multiple times.

You can only use this route if session passed the duplicate step (and was validated or rejected).

Request

POST
/v1/sessions/{SESSION_ID}/unenroll
curl --location --request POST 'https://api.pop.anima.io/v1/sessions/{SESSION_ID}/unenroll' \
--header 'Api-Key: {YOUR_API_KEY}'
GET/v1/personhood/{WALLET}/is-approved

Is Wallet Approved

This endpoint allows you to check if a wallet is validated as been validated in your application.

Optional URL Parameters

  • Name
    before
    Type
    string
    Description

    Unix timestamp in seconds. If provided, the endpoint will return if the wallet as been approved before the timestamp.

Request

GET
/v1/personhood/{WALLET}/is-approved
curl --location --request GET 'https://api.pop.anima.io/v1/personhood/{WALLET}/is-approved' \
--header 'Api-Key: {YOUR_API_KEY}'

Response

{
    "isApproved": true
}
GET/v1/personhood/{WALLET}/search

Search Wallet

This endpoint allows you to search for all the session made by a specific wallet in your application.

Optional URL Parameters

  • Name
    before
    Type
    string
    Description

    Unix timestamp in seconds. If provided, the endpoint will return only session before the timestamp.

  • Name
    limit
    Type
    number
    Description

    Number of sessions to return. Default is 10.

  • Name
    lastSessionId
    Type
    string
    Description

    If provided, the endpoint will return sessions after the provided session id.

  • Name
    sorting
    Type
    string
    Description

    DESC (by creation date) by default, can be ASC or DESC.

Response

Response is an Array of Sessions. Please refer to the session details endpoint for more information.

Request

GET
/v1/personhood/{WALLET}/search
curl --location --request GET 'https://api.pop.anima.io/v1/personhood/{WALLET}/search' \
--header 'Api-Key: {YOUR_API_KEY}'

Response

[{
    "session": {
        "id": "f0eb93a4-f086-4f9a-803b-2b61892d4292",
        "sandbox": false,
        "state": "REJECTED",
        "info": "FOUND_DUPLICATE"
    },
    "app": {
        "name": "Your app name",
        "logo_url": "logo.jpg",
        "verify": true,
        "force_wallet": true
    },
    "verifier": {
        "id": "anima:verifier:[email protected]",
        "public_address": "0x684ac6ce9fd2e3a6ffab4f0debe5b529f4421a22",
        "chain": "ETH"
    },
    "issuer": {
        "id": "anima:issuer:[email protected]",
        "public_address": "0xBe053D9BaC9Dc64E32E150eddd737c8434e304c6",
        "chain": "ETH"
    },
    "user": {
        "anima": false,
        "wallet": ""
    },
    "facegraph": {
        "hash": "",
        "id": ""
    },
    "duplicates": [
    {
        "session_id": "f0eb93a4-f086-4f9a-803b-2b61892d4292",
        "wallet": "0x684ac6ce9fd2e3a6ffab4f0debe5b529f4421a22"
    }
    ]
}]