# SDK / API Integration Overview

The Humanity Public Dev API gives developers end-to-end guide for integrating with Humanity’s verification platform

## Key Concepts

Understanding three core concepts will help you navigate the API surface:

### **Presets**

Predefined verification checks such as `is_human`, `is_21_plus`

### **Attestations**

Signed statements Humanity issues after performing verification (e.g., *“government ID verified”*, *“liveness completed”*).

Attestations are the building blocks behind presets.

### **Evidence payloads**

Secure data to derive attestations.

* Presets are the verification questions your application asks.
* Each preset is evaluated using one or more attestations performed by Humanity.
* The result is returned to your application along with an evidence payload that can be audited without exposing raw user data.

```
┌──────────────────────────────┐
│          Preset              │
│  (What your app asks)        │
│                              │
│  is_human                    │
│  is_21_plus                  │
│  humanity_user               │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        Attestations          │
│  (What Humanity verifies)    │
│                              │
│  • Liveness completed        │
│  • Government ID verified    │
│  • Age threshold met         │
└─────────────┬────────────────┘
              │
              ▼
┌──────────────────────────────┐
│        Evidence Payloads     │
│  (What is returned securely) │
│                              │
│  • Timestamps                │
│  • Issuer + signatures       │
│  • Verified attributes       │
└──────────────────────────────┘

```

***

## What you can build

* Verify specific user claims (e.g. age, humanity status).
* Authenticate users and manage consent using OAuth.
* Access validated user identity data.
* Keep systems in sync as authorizations or credentials change.

One common approach is an **OAuth-based flow**, shown below (**similar to Google or Stripe**).

```
┌──────────────────┐
│     Your App     │
└─────────┬────────┘
          │
          │ 1. Redirect user to /oauth/authorize
          ▼
┌──────────────────────────────────┐
│  Humanity OAuth /authorize       │
│  (User sees consent + performs   │
│   required verification)         │
└─────────┬────────────────────────┘
          │ 2. User completes consent
          │    and is redirected back
          ▼
┌──────────────────────────────────┐
│   Redirect Back (your redirect)  │
└─────────┬────────────────────────┘
          │ 3. Exchange authorization code
          ▼
┌──────────────────────────────────┐
│     /oauth/token                 │
│     (Get access token)           │
└─────────┬────────────────────────┘
          │ 4. Call preset endpoint
          ▼
┌──────────────────────────────────┐
│   /presets/<preset_name>         │
│   (e.g., is_human, is_21_plus)   │
└─────────┬────────────────────────┘
          │ 5. Receive verdict / result
          ▼
┌─────────────────┐
│     Your App    │
└─────────────────┘
```

The example below demonstrates a simple application that uses verified email and connected social accounts to tailor user content:

<a href="https://demo.humanity.org/newsletter-demo" class="button primary" data-icon="arrow-up-right-from-square">Personalized Newsletter Demo App</a><br>

***

## When to use the SDK vs the API

Use the API directly for custom integrations, non-TypeScript stacks, or generic OAuth/OIDC clients.

Use the SDK when building Node.js or TypeScript applications that benefit from typed helpers and reduced boilerplate.

### Getting started

| 📦 **@humanity-org/connect-sdk**                                                                            | 💻 **API Reference**                                     |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| A TypeScript SDK for working with the Humanity API                                                          | Complete documentation for every API endpoint            |
| [](https://docs.humanity.org/build-with-humanity/build-with-the-sdk-api/humanity-org-connect-sdk "mention") | [API Reference](https://docs.humanity.org/api-reference) |