After a user completes (or exits) the consent flow, they’re redirected to yourDocumentation Index
Fetch the complete documentation index at: https://docs.emergedata.ai/llms.txt
Use this file to discover all available pages before exploring further.
redirect_uri with query parameters indicating the result.
Callback parameters
| Parameter | Always Present | Description |
|---|---|---|
status | Yes | success, reauthorized, or failure |
state | Yes | The state value you provided in the link |
uid | Yes | The user identifier returned by Emerge. If you provided uid, you get the same value; if you omitted it, Emerge generates a pairwise uid. |
error_code | Only on failure | Error code explaining the failure |
Status values
success
First-time consent granted. This user has connected their data for the first time with your application.
reauthorized
User re-linked an existing consent. This happens when:
- User clicks the link again after previously consenting
- User re-authenticates after token expiration
failure
User cancelled or an error occurred during the flow.
Error codes
| Error Code | Description | Suggested Action |
|---|---|---|
user_failed | User cancelled or denied consent | Show retry option |
data_invalid | Insufficient data in user’s account | Explain data requirements |
access_denied | User denied OAuth permissions | Explain why permissions are needed |
invalid_scope | Required scopes not available | Contact support |
admin_policy_enforced | Organization policy blocks access | User needs admin approval |
uid_conflict | Different user already linked with this uid | Use a unique uid per user |
Handling callbacks
State verification
Recommended state storage
| Storage | Pros | Cons |
|---|---|---|
| Session | Simple, automatic cleanup | Requires session middleware |
| Redis | Distributed, TTL support | Additional infrastructure |
| Database | Persistent, auditable | More complex queries |
| Signed cookie | Stateless | Size limitations |
What happens after success
When you receivesuccess or reauthorized:
- Data export starts automatically - Emerge begins exporting the user’s data from their provider
- Export takes 1-15 minutes - Depending on data volume
- Webhook updates (optional) - You may receive consent events plus
data.ready/data.failedfor provider-level export updates - Poll export readiness (recommended fallback) - Check
GET /export/status/{uid}and query only when the provider insources[]hasdata_ready: true
Use provider-level readiness from
sources[] instead of assuming all providers are ready at once.Completed session handling
If a user clicks a consent link after they’ve already completed consent:- They see a brief “already connected” message
- They’re redirected to the Data Wallet (not back to your
redirect_uri) - No new callback is triggered