# 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            |
| [@humanity-org/connect-sdk](/build-with-humanity/build-with-the-sdk-api/humanity-org-connect-sdk.md) | [API Reference](https://docs.humanity.org/api-reference) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humanity.org/build-with-humanity/build-with-the-sdk-api/humanity-org-connect-sdk/sdk-api-integration-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.