Snapshots

A snapshot is the unit of underwriting data on Guild. One snapshot per user per fetch. Signed, scoped, timestamped, verifiable. You fetch one when you decide. You verify the signature. You feed the JSON into your model. The fields are what they say they are.

Fetching

curl https://api.guild.com.ng/partner/v1/users/usr_01HMFB.../snapshot \
  -H "Authorization: Bearer gld_live_01HKBZ..." \
  -H "X-Guild-Consent-Token: cnst_01HMFC..."

Response 200 with the snapshot JSON. Response time: median 95ms, p99 280ms. You can pass a ledger_window_days query parameter to override the consent’s default window (within the bounds of the granted scope). Useful if a consent allows up to 365 days but you only want the last 30 for a specific calculation:

curl 'https://api.guild.com.ng/partner/v1/users/usr_01HMFB.../snapshot?ledger_window_days=30' \
  -H "Authorization: Bearer gld_live_..." \
  -H "X-Guild-Consent-Token: cnst_..."

The full payload

{
  "userId": "usr_01HMFB7ZQK2X8YN4P5R6S7T8V9",
  "actorRole": "JOB_SEEKER",
  "standingTier": "Trusted",
  "standingScore": 612,
  "tierProgress": {
    "currentTier": "Trusted",
    "nextTier": "Established",
    "pointsToNext": 138,
    "trend30d": "rising"
  },
  "signals": {
    "completedJobsLast90d": 38,
    "averageReviewLast90d": 4.7,
    "onTimeRate": 0.96,
    "repaymentStreak": 12,
    "lifetimeEarnedKobo": "458200000",
    "channelDiversity": 0.83,
    "tenureDays": 187,
    "distinctEmployersLast90d": 9,
    "weeklyVolumeStability": 0.79,
    "savingsActiveRule": true,
    "lastActiveAt": "2026-08-14T09:21:08Z"
  },
  "ledgerWindow": {
    "days": 90,
    "totalInflowsKobo": "458200000",
    "totalOutflowsKobo": "402100000",
    "transactionCount": 47,
    "uniqueCounterparties": 11,
    "averageInflowKobo": "9744680",
    "medianInflowKobo": "8000000",
    "inflowVarianceKobo": "12400000",
    "windowStart": "2026-05-16T00:00:00Z",
    "windowEnd": "2026-08-14T00:00:00Z"
  },
  "kyc": {
    "tier": 3,
    "bvnVerified": true,
    "ninVerified": true,
    "addressVerified": true,
    "verifiedAt": "2026-04-12T08:42:17Z",
    "businessKyc": null
  },
  "repaymentHistory": {
    "totalLoansAcrossPartners": 2,
    "activeLoansAcrossPartners": 0,
    "totalRepaidKobo": "75000000",
    "totalDefaultedKobo": "0",
    "longestStreakDays": 87,
    "currentStreakDays": 0
  },
  "consent": {
    "id": "cnst_01HMFC...",
    "scopes": ["standing", "ledger_window_90", "kyc_status", "repayment_history"],
    "grantedAt": "2026-08-14T10:58:21Z",
    "expiresAt": "2026-11-14T10:58:21Z"
  },
  "signedAt": "2026-08-14T11:02:33Z",
  "signature": "ed25519:5e8a4f...c2b1"
}

The shape is consistent — fields you don’t have scope to read are present but null (or absent for collections). This lets your code use the same parser regardless of which scopes the consent granted.

Field semantics

The signals are the heart of the snapshot. Detailed semantics so you can build your model against precise definitions.

Standing

Field	Type	Meaning
`standingTier`	enum	`Building`, `Emerging`, `Trusted`, `Established`. The model’s classification.
`standingScore`	int 0-1000	The raw score behind the tier. Useful for fine-grained underwriting policies (e.g., “approve at score ≥600 even if tier reads Emerging”).
`tierProgress.pointsToNext`	int	How many points until the user crosses into the next tier. Useful for trajectory analysis.
`tierProgress.trend30d`	enum	`rising`, `stable`, `falling`. Whether the score moved up, down, or stayed flat in the last 30 days.

Job/work signals

Field	Type	Meaning
`completedJobsLast90d`	int	Count of applications with `status = COMPLETED` in the trailing 90 days.
`averageReviewLast90d`	float 0-5	Mean star rating from employers, weighted equally per review.
`onTimeRate`	float 0-1	Share of shifts where the user was marked present on time (not late).
`distinctEmployersLast90d`	int	Number of unique employers in the trailing 90 days. A diversity signal.
`tenureDays`	int	Days since the user’s account was created.

Cashflow signals

Field	Type	Meaning
`lifetimeEarnedKobo`	string-int	Total kobo earned across all completed jobs since account creation. String to preserve precision on large values.
`weeklyVolumeStability`	float 0-1	Coefficient of inverse variance on weekly earnings. Higher means more consistent week-to-week.
`savingsActiveRule`	bool	Whether the user has at least one active savings rule. A small positive signal of cashflow discipline.
`channelDiversity`	float 0-1	Normalized entropy across the channels the user has used. Higher means more rails actually used.
`lastActiveAt`	ISO-8601	When the user last took an action on Guild.

Ledger window (aggregated)

The ledger window is the user’s transaction summary over the requested time range. We don’t expose individual transactions — only aggregates.

Field	Meaning
`totalInflowsKobo`	All money that landed in the user’s wallet during the window.
`totalOutflowsKobo`	All money that left the wallet (withdrawals, savings, bills, refunds).
`transactionCount`	Total transaction rows in the window.
`uniqueCounterparties`	Distinct counterparties (employer names for inflows, beneficiary banks for outflows).
`averageInflowKobo`	Mean per-inflow size.
`medianInflowKobo`	Median per-inflow size. Less skewed than mean by outliers.
`inflowVarianceKobo`	Statistical variance of inflows. Used by some models to gauge income stability.

For traders, the ledger window also includes dailyAvgInflowKobo and distinctSendersLast30d.

KYC

Field	Meaning
`tier`	1, 2, or 3.
`bvnVerified`	True if the user has completed BVN verification through us.
`ninVerified`	True if the user has completed NIN verification through us.
`addressVerified`	True if the user has had their declared address verified (typically by document upload).
`verifiedAt`	When the highest verification step completed.
`businessKyc`	For traders/employers, additional business KYC (CAC, etc.) or null.

Repayment history

If the user has taken loans through any Guild-integrated lender:

Field	Meaning
`totalLoansAcrossPartners`	Count of loans the user has had, across all partners.
`activeLoansAcrossPartners`	Currently outstanding.
`totalRepaidKobo`	Cumulative principal + interest repaid.
`totalDefaultedKobo`	Cumulative principal in default.
`longestStreakDays`	Longest consecutive on-time-payment streak in days.
`currentStreakDays`	Current on-time streak. Reset to 0 on a missed payment.

This scope is privacy-sensitive. We aggregate across partners — you don’t see which partner extended the credit, only that someone did.

Signature verification

This is the part you must implement carefully. The signature covers a canonical JSON serialisation of the entire payload (except the signature field itself). We use Ed25519. Our public keys are at GET /partner/v1/keys:

{
  "keys": [
    {
      "kid": "guild-prod-2026-q3",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "MCowBQYDK2VwAyEAa9...",
      "alg": "EdDSA",
      "use": "sig",
      "validFrom": "2026-07-01T00:00:00Z",
      "validUntil": "2026-09-30T23:59:59Z"
    },
    {
      "kid": "guild-prod-2026-q4",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "MCowBQYDK2VwAyEABx...",
      "alg": "EdDSA",
      "use": "sig",
      "validFrom": "2026-09-15T00:00:00Z",
      "validUntil": "2026-12-31T23:59:59Z"
    }
  ]
}

We rotate keys quarterly with a 30-day overlap window. During overlap, snapshots may be signed with either the outgoing or incoming key. Verification steps:

Pull the keys

Cache for up to 4 hours. Don’t fetch per snapshot.

Look up the kid

The signature contains a kid reference. Find the matching public key.

Canonicalise the payload

Remove the signature field. Sort keys lexicographically at every level. Serialise with no extra whitespace.

Verify

Standard Ed25519 verification. If invalid, reject the snapshot — do not pass it to your underwriting model.

We provide reference implementations in Python, Node.js, and Go on the Partner Portal under “Resources.” Use those rather than implementing from scratch.

What’s not in a snapshot

Things you might expect but won’t find:

Transaction-level details. Only aggregates. (Privacy.)
Counterparty names. “11 unique counterparties” not “Adekunle, Olabisi, Funmi, …”. (Privacy.)
The user’s bank account number or BVN. We hold those. They don’t leave Guild. (Security.)
GPS coordinates or device IDs. We don’t collect them.
Voice transcripts or message contents. We have them; we don’t share them.

The snapshot is engineered for underwriting. Not surveillance.

Caching

A snapshot is a point-in-time read. You can cache it on your side for the duration of your underwriting decision. Don’t cache it indefinitely. A user’s standing tier can change daily; an underwriting decision made on stale data is bad for the borrower and bad for you. Reasonable cache TTL: the length of your decisioning window (e.g., if you decide within 5 minutes of fetch, cache for 5 minutes). If you need a fresh read, fetch a new snapshot. Each fetch is independent and signed with the timestamp.

Idempotency

Snapshot fetches are read-only and inherently idempotent. No Idempotency-Key header needed.

Errors

HTTP	error_code	When
401	`missing_auth`	No Authorization header.
401	`invalid_auth`	Bearer token doesn’t match an active key.
403	`consent_missing`	No `X-Guild-Consent-Token` header.
403	`consent_not_found`	Consent ID doesn’t exist or doesn’t belong to your partner.
403	`consent_revoked`	Consent was revoked.
403	`consent_expired`	Consent passed its expiry.
403	`scope_insufficient`	Your key’s scope doesn’t cover the operation.
404	`user_not_found`	User ID doesn’t exist or has deleted their account.
429	`rate_limited`	Per-key bucket exceeded. Retry-After header indicates the wait.
500	`internal`	Unexpected error. Includes a `requestId` for support.

Webhooks

Real-time notifications when consents change, tiers move, or repayments land.

Rate limits

Per-key throughput, bursts, and dedicated capacity options.

Get Started

For Job Seekers

For Traders

For Employers

For Partners

Channels

Standing & the Ledger

Architecture

Security & Trust

Fetching

The full payload

Field semantics

Standing

Job/work signals

Cashflow signals

Ledger window (aggregated)

KYC

Repayment history

Signature verification

What’s not in a snapshot

Caching

Idempotency

Errors

Next

Webhooks

Rate limits

​Fetching

​The full payload

​Field semantics

​Standing

​Job/work signals

​Cashflow signals

​Ledger window (aggregated)

​KYC

​Repayment history

​Signature verification

​What’s not in a snapshot

​Caching

​Idempotency

​Errors

​Next

Webhooks

Rate limits

Fetching

The full payload

Field semantics

Standing

Job/work signals

Cashflow signals

Ledger window (aggregated)

KYC

Repayment history

Signature verification

What’s not in a snapshot

Caching

Idempotency

Errors

Next