Getting started
Choose your integration path
Decision tree for identification, signing, wildcard, and document endpoints on API v2.
Use this tree before reading the full API reference.
What are you building?
What are you building?
│
├── Mobile app — user and pasby on the same device
│ ├── Authentication / onboarding
│ │ └── POST /api/v2/identification/same-device
│ └── Sign or confirm a transaction
│ └── POST /api/v2/signing/same-device
│
├── Web app — user starts on your site, completes on phone
│ ├── Authentication / onboarding
│ │ └── POST /api/v2/identification/different-device
│ │ (or OIDC — see /docs/oidc)
│ └── Sign or confirm
│ └── POST /api/v2/signing/different-device
│
├── User identity unknown upfront (secure-start / QR)
│ ├── Identification
│ │ └── POST /api/v2/identification/wildcard
│ └── Signing
│ └── POST /api/v2/signing/wildcard
│
└── Document / PDF signing
├── Simple: sign file for NIN list
│ └── POST /api/v2/document/signing
├── Rich UI: multiple signees with metadata
│ └── POST /api/v2/document/review
└── Stalled flow recovery
└── POST /api/v2/document/refreshAfter starting any flow
Track completion using one of:
| Mechanism | Endpoint | Best for |
|---|---|---|
| Client polling | POST /api/v2/flow/ping | Any client; you control interval |
| Server-sent events | GET /api/v2/flow/sse | Web apps with live status UI |
| Long poll (legacy) | POST /api/v2/flow/polling | Simplest client; prefer ping/SSE for v2 |
Always implement cancel (POST /api/v2/flow/cancel) when the user can abandon your UI.
Device patterns
| Pattern | Suffix | When to use |
|---|---|---|
| Same-device | /same-device | User completes on the device running your app (typical mobile) |
| Different-device | /different-device | User starts in browser, finishes on phone |
| Wildcard | /wildcard | NIN unknown upfront; uses seeds (1–10) for secure-start |
Actions
Identification: login, signup, link
Signing: sign (webhook required), confirm (no webhook)
See Claims reference for claim strings and Guides for step-by-step flows.