Consent links

A consent link is a one-time URL that takes a user to a Guild consent prompt for your organisation. The user authenticates with their Guild credentials (phone + OTP), reviews the consent prompt, and grants or declines. The flow is OAuth-shaped: redirect, prompt, callback (or webhook).

POST /partner/v1/consent-links

Body

string

required

The user’s phone number in E.164 format (e.g., +2348031234567). We resolve to a Guild user during their consent flow.

array

required

List of scope strings the consent will grant. See Partner → Consent for the full scope vocabulary.Example: ["standing", "ledger_window_90", "kyc_status", "repayment_history"]

integer

required

How many days the consent should last once granted. Valid values: 30, 60, 90, 180, 365.

string

Optional. URL the user is redirected to after granting or declining. Receives ?status=granted&consentId=cnst_... or ?status=declined.

integer

default:"48"

How long the consent link itself is valid before the user has acted on it. After this, the link is dead and you’d need to generate a new one.

object

Optional. Arbitrary key-value pairs you want associated with the consent for your internal reference. Returned in the consent record.

Required headers

string

required

Bearer <api_key> with write:consent-links scope.

string

Recommended for safe retries.

Example

curl -X POST https://api.guild.com.ng/partner/v1/consent-links \
  -H "Authorization: Bearer gld_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8e4f3a2b-1c2d-3e4f-5a6b-7c8d9e0f1a2b" \
  -d '{
    "userPhone": "+2348031234567",
    "scopes": ["standing", "ledger_window_90", "kyc_status"],
    "expiresInDays": 90,
    "callbackUrl": "https://yourbank.com.ng/loan/12345/consent-result"
  }'

Response 201

ULID prefixed clnk_.

The URL to send the user to.

string

ISO-8601. When the consent link itself expires (separate from the consent’s own expiry once granted).

{
  "consentLinkId": "clnk_01HMFB7ZQK2X8YN4P5R6S7T8V9",
  "consentUrl": "https://guild.com.ng/consent/clnk_01HMFB7ZQK2X8YN4P5R6S7T8V9",
  "expiresAt": "2026-08-16T11:00:00Z"
}

Drive the user through the flow

You redirect (or send a deep link via SMS or email) the user to consentUrl. They:

Sign in to Guild with their phone + OTP.
See the consent prompt — your organisation’s name, the scopes you’re requesting, the expiry duration.
Tap Grant or Decline.
Redirect back to your callbackUrl with ?status=granted&consentId=cnst_... or ?status=declined&reason=user_declined.

If callbackUrl was not provided, the user stays on Guild and sees a confirmation message; you receive the result via the consent.granted (or consent.revoked later) webhook.

GET /partner/v1/consent-links/{consentLinkId}

Useful for polling if you didn’t configure a webhook.

Response 200

As issued.

string

Masked (e.g., +2348********67).

string

One of PENDING, CONSENT_GRANTED, CONSENT_DECLINED, EXPIRED.

If CONSENT_GRANTED, the resulting consent ID. Null otherwise.

array

As requested.

object

As supplied.

string

ISO-8601.

string

ISO-8601 of when the user granted or declined. Null if still PENDING.

string

ISO-8601.

GET /partner/v1/consents/{consentId}

Response 200

string

ULID prefixed cnst_.

string

The user this consent is for.

string

Your partner ID.

string

One of ACTIVE, EXPIRED, REVOKED.

array

As granted.

string

ISO-8601.

string

ISO-8601.

string

ISO-8601, null if not revoked.

string

Free-text reason or null.

ULID, if the consent was created via a consent link.

List your consents

GET /partner/v1/consents

Query parameters

string

Filter to consents for a specific user.

string

Filter by ACTIVE / EXPIRED / REVOKED.

integer

default:"50"

Page size. Max 200.

string

For pagination. Returned in the previous response.

Response 200

{
  "data": [/* array of consent records */],
  "nextCursor": "eyJpZCI6ImNuc3RfMDFI...",
  "hasMore": true
}

Snapshots

Use the consent ID to read snapshots.

Webhooks

consent.granted, consent.revoked events.

Get Started

Partner API

Webhooks

Consent links

Body

Required headers

Example

Response 201

Drive the user through the flow

Response 200

Response 200

List your consents

Query parameters

Response 200

What to read next

Snapshots

Webhooks

​Create a consent link

​Body

​Required headers

​Example

​Response 201

​Drive the user through the flow

​Get a consent link’s status

​Response 200

​Get a consent record

​Response 200

​List your consents

​Query parameters

​Response 200

​What to read next

Snapshots

Webhooks

Create a consent link

Body

Required headers

Example

Response 201

Drive the user through the flow

Get a consent link’s status

Response 200

Get a consent record

Response 200

List your consents

Query parameters

Response 200

What to read next