Snapshots

The endpoint you’ll use most. Returns a signed JSON document with the user’s standing tier, score, behavioural signals, and an aggregated view of their audit ledger over the consented window.

Fetch a snapshot

GET /partner/v1/users/{userId}/snapshot

Path parameters

string

required

The Guild user ID. ULID, prefixed usr_.

Query parameters

integer

default:"consent_default"

Override the ledger window for this read. Must be ≤ the maximum permitted by the consent. Valid values: 30, 60, 90, 365.

Required headers

string

required

Bearer <api_key>. See Authentication.

The active consent ID for this user. ULID, prefixed cnst_.

Example

curl https://api.guild.com.ng/partner/v1/users/usr_01HMFB7ZQK2X8YN4P5R6S7T8V9/snapshot \
  -H "Authorization: Bearer gld_live_01HKBZ4PQ9Z3K7T8V9X2Y1B5C6" \
  -H "X-Guild-Consent-Token: cnst_01HMFC4PQ9Z3K7T8V9X2Y1B5C6"

Response 200

string

User identifier.

string

One of JOB_SEEKER, TRADER, EMPLOYER.

string

One of Building, Emerging, Trusted, Established.

integer

Raw score 0-1000 behind the tier classification.

object

Show properties

string

Same as standingTier at root.

string

The next tier up (null if at Established).

integer

Points the user needs to gain to cross into the next tier.

string

One of rising, stable, falling. Trajectory over the trailing 30 days.

object

Show properties

integer

Count of completed applications in the trailing 90 days.

number

Mean star rating from employer reviews. 0-5.

number

Share of shifts where the user was marked on time. 0-1.

integer

Consecutive on-time loan repayments across all partners.

string

Total kobo earned across all completed jobs since account creation. String-encoded BigInt.

number

Normalised entropy across channels the user has used. 0-1.

integer

Days since the user joined Guild.

integer

Unique employers who hired this user in the trailing 90 days. (JOB_SEEKER only.)

number

Coefficient of inverse variance on weekly earnings. Higher = more stable.

boolean

Whether the user has at least one active savings rule.

string

ISO-8601 timestamp of the user’s last action on Guild.

object

Show properties

integer

Window size in days.

string

All money landing in the user’s wallet during the window.

string

All money leaving the wallet during the window.

integer

Total transaction rows in the window.

integer

Distinct senders for inflows + recipients for outflows.

string

Mean per-inflow size.

string

Median per-inflow size.

string

Statistical variance of inflows.

string

ISO-8601.

string

ISO-8601.

object

Show properties

integer

1, 2, or 3.

boolean

Whether BVN verification has completed.

boolean

Whether NIN verification has completed.

boolean

Whether address verification has completed.

string

ISO-8601 of the highest-tier verification timestamp.

object

For traders/employers, additional business KYC fields or null.

object

Only present if the consent includes the repayment_history scope.

Show properties

integer

Count of loans the user has had across all partners.

integer

Currently outstanding.

string

Cumulative principal + interest repaid.

string

Cumulative principal in default.

integer

Longest consecutive on-time-payment streak in days.

integer

Current on-time streak.

Show properties

string

Consent ID.

array

Array of scope strings granted by the consent.

string

ISO-8601.

string

ISO-8601.

string

ISO-8601 of when this snapshot was signed.

string

Ed25519 signature in the format ed25519:<base64>. See verification guidance.

Example response

{
  "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_01HMFC4PQ9Z3K7T8V9X2Y1B5C6",
    "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"
}

Verifying the signature

Pull the public keys at GET /partner/v1/keys (cache up to 4 hours). The signature header includes a kid reference; match it to the public key with the same kid. Verification procedure:

Remove the signature field

The signature was computed over the payload without itself.

Canonicalise the JSON

Sort keys lexicographically at every level. Serialise with no extra whitespace.

Verify

Standard Ed25519 verification of the canonical bytes against the public key.

Reference implementations in Python, Node.js, and Go are available on the Partner Portal under “Resources.”

Error cases

HTTP	Code	When
401	`missing_auth`	No Authorization header
401	`invalid_auth`	Token not recognised
403	`consent_missing`	No `X-Guild-Consent-Token` header
403	`consent_not_found`	Consent ID isn’t yours
403	`consent_revoked`	User revoked it
403	`consent_expired`	Past `expiresAt`
403	`consent_scope_mismatch`	The requested `ledger_window_days` exceeds the consent’s scope
404	`user_not_found`	User deleted their account
429	`rate_limited`	Per-key burst exceeded

Get the public keys

GET /partner/v1/keys

Returns the current set of public keys for signature verification. Rotated quarterly with a 30-day overlap window.

Response

{
  "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"
    }
  ]
}

Cache the response client-side. Don’t fetch per snapshot.

Consent links

How to ask a user for consent before fetching their snapshot.

Disbursements

Disbursing approved credit over OPay payout.

Get Started

Partner API

Webhooks

Fetch a snapshot

Path parameters

Query parameters

Required headers

Example

Response 200

Example response

Verifying the signature

Error cases

Get the public keys

Response

What to read next

Consent links

Disbursements

​Fetch a snapshot

​Path parameters

​Query parameters

​Required headers

​Example

​Response 200

​Example response

​Verifying the signature

​Error cases

​Get the public keys

​Response

​What to read next

Consent links

Disbursements

Fetch a snapshot

Path parameters

Query parameters

Required headers

Example

Response 200

Example response

Verifying the signature

Error cases

Get the public keys

Response

What to read next