Human Verification

Search human verifications

get

Returns human verifications matching the given search criteria.

Query parameters

connectionScopestring · enumOptional

Narrow the pool to the viewer's connections. 'all' = no filter; 'following' = subjects the viewer follows on X; 'network' = subjects in the viewer's "people you know" set (connection degrees 1st/2nd/3rd-subject). Falls back to 'all' without an authenticated viewer.

Default: allPossible values:

followsScopestring · enumOptionalPossible values:

minScoreinteger · max: 2800Optional

searchstring · min: 2 · max: 100Optional

sortBystring · enumOptionalDefault: newestPossible values:

sortOrderstring · enumOptionalDefault: descPossible values:

statusany ofOptionalDefault: ["REQUESTED"]

string · enumOptionalPossible values:

or

minVerificationsinteger · max: 2Optional

limitinteger · max: 50OptionalDefault: 50

offsetinteger · max: 2147483647OptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/human-verification/search

HTTPcURLJavaScriptPython

GET /api/v2/human-verification/search HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "bonds": [
        {
          "id": 1,
          "bondType": "text",
          "statement": "text",
          "amount": "text",
          "amountType": "text",
          "expiration": "text",
          "authorProfileId": 1,
          "subjectUserId": 1,
          "archived": true,
          "archivedAt": "text",
          "archiveReason": "text",
          "createdAt": "text",
          "updatedAt": "text",
          "metadata": {
            "subjectUserkey": "text",
            "verificationMethod": "IRL",
            "comment": "text"
          },
          "author": {
            "id": 1,
            "profileId": 1,
            "displayName": "text",
            "username": "text",
            "avatarUrl": "https://example.com",
            "description": "text",
            "score": 1,
            "status": "ACTIVE",
            "userkeys": [
              "text"
            ],
            "xpTotal": 1,
            "xpStreakDays": 1,
            "xpRemovedDueToAbuse": true,
            "influenceFactor": 1,
            "influenceFactorPercentile": 1,
            "humanVerificationStatus": "REQUESTED",
            "validatorNftCount": 1,
            "links": {
              "profile": "https://example.com",
              "scoreBreakdown": "https://example.com"
            },
            "stats": {
              "review": {
                "received": {
                  "negative": 1,
                  "neutral": 1,
                  "positive": 1
                }
              },
              "vouch": {
                "given": {
                  "amountWeiTotal": 1,
                  "count": 1
                },
                "received": {
                  "amountWeiTotal": 1,
                  "count": 1
                }
              }
            }
          },
          "links": {
            "activity": "https://example.com"
          }
        }
      ],
      "connectionDegree": "1st",
      "createdAt": "text",
      "expiresAt": "text",
      "hasSelfDeclaredBond": true,
      "id": 1,
      "selfDeclaredBondId": 1,
      "status": "REQUESTED",
      "subject": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      },
      "verifiedAt": "text",
      "viewerFollowsThem": true
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get human verifications created by the current user

get

Returns human verifications where the subject has a bond created by the authenticated user.

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · max: 50OptionalDefault: 50

offsetinteger · max: 2147483647OptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

404

Not found

application/json

500

Internal server error

application/json

get/human-verification/my-verifications

HTTPcURLJavaScriptPython

GET /api/v2/human-verification/my-verifications HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "bonds": [
        {
          "id": 1,
          "bondType": "text",
          "statement": "text",
          "amount": "text",
          "amountType": "text",
          "expiration": "text",
          "authorProfileId": 1,
          "subjectUserId": 1,
          "archived": true,
          "archivedAt": "text",
          "archiveReason": "text",
          "createdAt": "text",
          "updatedAt": "text",
          "metadata": {
            "subjectUserkey": "text",
            "verificationMethod": "IRL",
            "comment": "text"
          },
          "author": {
            "id": 1,
            "profileId": 1,
            "displayName": "text",
            "username": "text",
            "avatarUrl": "https://example.com",
            "description": "text",
            "score": 1,
            "status": "ACTIVE",
            "userkeys": [
              "text"
            ],
            "xpTotal": 1,
            "xpStreakDays": 1,
            "xpRemovedDueToAbuse": true,
            "influenceFactor": 1,
            "influenceFactorPercentile": 1,
            "humanVerificationStatus": "REQUESTED",
            "validatorNftCount": 1,
            "links": {
              "profile": "https://example.com",
              "scoreBreakdown": "https://example.com"
            },
            "stats": {
              "review": {
                "received": {
                  "negative": 1,
                  "neutral": 1,
                  "positive": 1
                }
              },
              "vouch": {
                "given": {
                  "amountWeiTotal": 1,
                  "count": 1
                },
                "received": {
                  "amountWeiTotal": 1,
                  "count": 1
                }
              }
            }
          },
          "links": {
            "activity": "https://example.com"
          }
        }
      ],
      "connectionDegree": "1st",
      "createdAt": "text",
      "expiresAt": "text",
      "hasSelfDeclaredBond": true,
      "id": 1,
      "selfDeclaredBondId": 1,
      "status": "REQUESTED",
      "subject": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      },
      "verifiedAt": "text",
      "viewerFollowsThem": true
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get human verification bonds

get

Returns all HUMAN bonds with subject and actor info, ordered by creation date descending.

Query parameters

limitinteger · max: 50OptionalDefault: 50

offsetinteger · max: 2147483647OptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/human-verification/verifications

HTTPcURLJavaScriptPython

GET /api/v2/human-verification/verifications HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "values": [
    {
      "bond": {
        "id": 1,
        "bondType": "text",
        "statement": "text",
        "amount": "text",
        "amountType": "text",
        "expiration": "text",
        "authorProfileId": 1,
        "subjectUserId": 1,
        "archived": true,
        "archivedAt": "text",
        "archiveReason": "text",
        "createdAt": "text",
        "updatedAt": "text",
        "metadata": {
          "subjectUserkey": "text",
          "verificationMethod": "IRL",
          "comment": "text"
        },
        "author": {
          "id": 1,
          "profileId": 1,
          "displayName": "text",
          "username": "text",
          "avatarUrl": "https://example.com",
          "description": "text",
          "score": 1,
          "status": "ACTIVE",
          "userkeys": [
            "text"
          ],
          "xpTotal": 1,
          "xpStreakDays": 1,
          "xpRemovedDueToAbuse": true,
          "influenceFactor": 1,
          "influenceFactorPercentile": 1,
          "humanVerificationStatus": "REQUESTED",
          "validatorNftCount": 1,
          "links": {
            "profile": "https://example.com",
            "scoreBreakdown": "https://example.com"
          },
          "stats": {
            "review": {
              "received": {
                "negative": 1,
                "neutral": 1,
                "positive": 1
              }
            },
            "vouch": {
              "given": {
                "amountWeiTotal": 1,
                "count": 1
              },
              "received": {
                "amountWeiTotal": 1,
                "count": 1
              }
            }
          }
        },
        "links": {
          "activity": "https://example.com"
        }
      },
      "subject": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Request human verification

post

Creates a human verification request for the authenticated user. Idempotent - succeeds if already requested.

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful response

application/json

successbooleanRequired

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/human-verification/request

HTTPcURLJavaScriptPython

POST /api/v2/human-verification/request HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true
}

Search eligible human verifiers

get

Returns eligible verifiers sorted by proximity to the current user. Used by requesters to find verifiers to reach out to.

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

searchstring · min: 2 · max: 100Optional

limitinteger · max: 50OptionalDefault: 50

offsetinteger · max: 2147483647OptionalDefault: 0

Responses

200

Successful response

application/json

totalnumberRequired

limitnumberRequired

offsetnumberRequired

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

404

Not found

application/json

500

Internal server error

application/json

get/human-verification/verifiers

HTTPcURLJavaScriptPython

GET /api/v2/human-verification/verifiers HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "values": [
    {
      "connectionDegree": "1st",
      "hasNudged": true,
      "user": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Get human verification info for a subject

get

Returns the human verification status, expiration, and any bonds where the subject is being verified. Accepts profile-userkeys (profileId:<n>) or X-account userkeys (service:x.com:<id>).

Path parameters

subjectUserkeyany ofRequired

stringOptional

or

stringOptional

Responses

200

Successful response

application/json

connectionDegreestring · enum · nullableRequiredPossible values:

createdAtstringRequired

expiresAtstring · nullableRequired

hasSelfDeclaredBondbooleanRequired

idinteger · max: 9007199254740991 · nullableRequired

selfDeclaredBondIdinteger · max: 9007199254740991 · nullableRequired

statusstring · enum · nullableRequiredPossible values:

verifiedAtstring · nullableRequired

viewerFollowsThembooleanRequired

400

Invalid input data

application/json

404

Not found

application/json

500

Internal server error

application/json

get/human-verification/{subjectUserkey}

HTTPcURLJavaScriptPython

GET /api/v2/human-verification/{subjectUserkey} HTTP/1.1
Host: api.ethos.network
Accept: */*

{
  "bonds": [
    {
      "id": 1,
      "bondType": "text",
      "statement": "text",
      "amount": "text",
      "amountType": "text",
      "expiration": "text",
      "authorProfileId": 1,
      "subjectUserId": 1,
      "archived": true,
      "archivedAt": "text",
      "archiveReason": "text",
      "createdAt": "text",
      "updatedAt": "text",
      "metadata": {
        "subjectUserkey": "text",
        "verificationMethod": "IRL",
        "comment": "text"
      },
      "author": {
        "id": 1,
        "profileId": 1,
        "displayName": "text",
        "username": "text",
        "avatarUrl": "https://example.com",
        "description": "text",
        "score": 1,
        "status": "ACTIVE",
        "userkeys": [
          "text"
        ],
        "xpTotal": 1,
        "xpStreakDays": 1,
        "xpRemovedDueToAbuse": true,
        "influenceFactor": 1,
        "influenceFactorPercentile": 1,
        "humanVerificationStatus": "REQUESTED",
        "validatorNftCount": 1,
        "links": {
          "profile": "https://example.com",
          "scoreBreakdown": "https://example.com"
        },
        "stats": {
          "review": {
            "received": {
              "negative": 1,
              "neutral": 1,
              "positive": 1
            }
          },
          "vouch": {
            "given": {
              "amountWeiTotal": 1,
              "count": 1
            },
            "received": {
              "amountWeiTotal": 1,
              "count": 1
            }
          }
        }
      },
      "links": {
        "activity": "https://example.com"
      },
      "translation": {
        "contentHash": "text",
        "detectedLanguage": "text",
        "translatedLanguage": "text",
        "translatedContent": "text",
        "translatedDescription": "text"
      }
    }
  ],
  "connectionDegree": "1st",
  "createdAt": "text",
  "expiresAt": "text",
  "hasSelfDeclaredBond": true,
  "id": 1,
  "selfDeclaredBondId": 1,
  "status": "REQUESTED",
  "subject": {
    "id": 1,
    "profileId": 1,
    "displayName": "text",
    "username": "text",
    "avatarUrl": "https://example.com",
    "description": "text",
    "score": 1,
    "status": "ACTIVE",
    "userkeys": [
      "text"
    ],
    "xpTotal": 1,
    "xpStreakDays": 1,
    "xpRemovedDueToAbuse": true,
    "influenceFactor": 1,
    "influenceFactorPercentile": 1,
    "humanVerificationStatus": "REQUESTED",
    "validatorNftCount": 1,
    "links": {
      "profile": "https://example.com",
      "scoreBreakdown": "https://example.com"
    },
    "stats": {
      "review": {
        "received": {
          "negative": 1,
          "neutral": 1,
          "positive": 1
        }
      },
      "vouch": {
        "given": {
          "amountWeiTotal": 1,
          "count": 1
        },
        "received": {
          "amountWeiTotal": 1,
          "count": 1
        }
      }
    }
  },
  "verifiedAt": "text",
  "viewerFollowsThem": true
}

Create a signature for a human verification bond

post

Creates a signed payload for submitting a HUMAN bond to the blockchain. The caller must then submit the bond to the blockchain themselves.

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

subjectProfileIdinteger · max: 9007199254740991Optional

subjectUserkeyany ofOptional

stringOptional

or

stringOptional

verificationMethodstring · enumRequiredPossible values:

commentstring · min: 1Required

Responses

200

Successful response

application/json

statementstringRequired

expirationstringRequired

amountstringRequired

amountTypestringRequired

metadatastringRequired

randValuenumberRequired

signaturestringRequired

65-byte ECDSA signature (0x-prefixed hex, 132 chars)

bondTypeconst: HUMAN_VERIFICATIONRequired

400

Invalid input data

application/json

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/signatures/humanity-bond

HTTPcURLJavaScriptPython

POST /api/v2/signatures/humanity-bond HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "subjectProfileId": 1,
  "subjectUserkey": "text",
  "verificationMethod": "IRL",
  "comment": "text"
}

{
  "statement": "text",
  "expiration": "text",
  "amount": "text",
  "amountType": "text",
  "metadata": "text",
  "randValue": 1,
  "signature": "text",
  "bondType": "text"
}

Create a signature for a self-declared human bond

post

Creates a signed payload for submitting a self-declared HUMAN bond to the blockchain. Any user with an Ethos profile can create one. Limited to one per profile.

Authorizations

Authorization

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful response

application/json

statementstringRequired

expirationstringRequired

amountstringRequired

amountTypestringRequired

metadatastringRequired

randValuenumberRequired

signaturestringRequired

65-byte ECDSA signature (0x-prefixed hex, 132 chars)

bondTypeconst: SELF_DECLARED_HUMANRequired

401

Authorization not provided

application/json

403

Insufficient access

application/json

500

Internal server error

application/json

post/signatures/self-declared-humanity-bond

HTTPcURLJavaScriptPython

POST /api/v2/signatures/self-declared-humanity-bond HTTP/1.1
Host: api.ethos.network
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "statement": "text",
  "expiration": "text",
  "amount": "text",
  "amountType": "text",
  "metadata": "text",
  "randValue": 1,
  "signature": "text",
  "bondType": "text"
}