Skip to content
API version 2026-10-29

Enrol your first customer in 10 minutes

Your customer ticks “List my business on Dalel” in your checkout. Your server sends us the owner and business basics. We prepare a private draft attributed to you and send the owner a one-time link. You never create accounts or handle passwords, and every step comes back to you as a signed webhook.

Overview

The enrolment API prefills and attributes, nothing more. The owner creates their own account with a code sent to their phone, reviews their page, and it goes through the same moderation as any business that signs up on Dalel directly.

EnvironmentKeyWhat happens
Sandboxdlpk_test_…No real messages; magic numbers script the outcome.
Livedlpk_live_…Enabled once the go-live checklist in the partner portal is green.

Quickstart

  1. Create a sandbox key

    Partner portal › Keys & webhooks › New key. The secret is shown once; keep it in your secrets store.

  2. Sign the request

    HMAC-SHA256 with the secret half of your key over: v1:{timestamp}:{nonce}:{METHOD}:{path}:{sha256_hex(raw_body)}

    bash · sign
    KEY="dlpk_test_xxxxxxxxxx.<secret>"   # shown once in the partner portal
    SECRET="${KEY#*.}"
    BODY=$(cat enrol.json)
    TS=$(date +%s)
    NONCE=$(uuidgen | tr 'A-Z' 'a-z')
    PATH_="/v1/partners/enrolments"
    BODY_SHA=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
    SIG=$(printf 'v1:%s:%s:POST:%s:%s' "$TS" "$NONCE" "$PATH_" "$BODY_SHA" \
      | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
  3. Enrol a customer

    In the sandbox, +218 91 000 0001 walks through to activation.

    curl · POST /v1/partners/enrolments
    curl -X POST "https://api.dalel.ly/v1/partners/enrolments" \
      -H "Content-Type: application/json" \
      -H "Dalel-Version: 2026-10-29" \
      -H "X-Dalel-Partner-Key: $KEY" \
      -H "X-Dalel-Timestamp: $TS" \
      -H "X-Dalel-Nonce: $NONCE" \
      -H "X-Dalel-Signature: t=$TS,v1=$SIG" \
      -H "X-Dalel-Idempotency-Key: crm-order-8841" \
      --data-binary "$BODY"
  4. Receive the webhook

    Verify X-Dalel-Signature and answer 2xx within 10 s. We retry after 5s → 30s → 2m → 10m → 1h → 6h → 24h.

  5. Request go-live

    When the portal checklist is green, Dalel enables live mode and you create a dlpk_live_ key.

Authentication (HMAC v1)

Every request carries these headers. The timestamp is in seconds and must be within 5 minutes of Dalel’s clock; the nonce is fresh and random on every request, retries included.

HeaderValue
X-Dalel-Partner-KeyThe full key: prefix, a dot, then the secret
X-Dalel-TimestampUnix epoch seconds (integer)
X-Dalel-NonceRandom value, up to 128 characters
X-Dalel-Signaturet={timestamp},v1={hex}
X-Dalel-Idempotency-KeyRequired on writes; reuse it when you retry
Dalel-Version2026-10-29

The signed string: v1:{timestamp}:{nonce}:{METHOD}:{path}:{sha256_hex(raw_body)}

Node / TypeScript
import { createHash, createHmac, randomUUID } from 'node:crypto';

export function signedHeaders(key: string, method: string, path: string, body: string) {
  const secret = key.slice(key.indexOf('.') + 1);
  const ts = String(Math.floor(Date.now() / 1000));
  const nonce = randomUUID();
  const bodySha = createHash('sha256').update(body).digest('hex');
  const canonical = `v1:${ts}:${nonce}:${method.toUpperCase()}:${path}:${bodySha}`;
  const sig = createHmac('sha256', secret).update(canonical).digest('hex');
  return {
    'Dalel-Version': '2026-10-29',
    'X-Dalel-Partner-Key': key,
    'X-Dalel-Timestamp': ts,
    'X-Dalel-Nonce': nonce,
    'X-Dalel-Signature': `t=${ts},v1=${sig}`,
  };
}

The same idempotency key with the same body replays the first response with Idempotent-Replayed: true. A different body under the same key is a 409.

POST /v1/partners/enrolments

Required: external_customer_id, the owner’s name, their phone or email, and the business name in Arabic or English. No consent proof is needed. metadata is optional: up to 20 flat keys.

Request body
{
  "external_customer_id": "SAH-00412",
  "owner": {
    "full_name": "Mohamed Ali",
    "phone": "+218912345678",
    "email": "[email protected]",
    "preferred_language": "ar"
  },
  "business": {
    "name_ar": "مخبز الياسمين",
    "category_hint": "bakery",
    "city": "Tripoli"
  },
  "context": { "trigger": "bill_payment" }
}
Response
HTTP/1.1 202 Accepted
Dalel-Version: 2026-10-29
X-Request-Id: req_…
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 41

{
  "success": true,
  "request_id": "req_…",
  "data": {
    "enrolment_id": "enr_…",
    "external_customer_id": "SAH-00412",
    "status": "received",
    "business_stage": null,
    "mode": "test",
    "invited_at": null,
    "reminders_sent": 0,
    "activated_at": null,
    "received_at": "2026-10-29T10:15:03Z",
    "updated_at": "2026-10-29T10:15:03Z"
  }
}
StatusMeaning
202New enrolment created
200Existing enrolment, or already on Dalel (already_registered: we message nobody, no commission)
422validation_failed with field errors, or suppressed: the person asked not to be enrolled by you

POST /v1/partners/enrolments/batch

For existing customers who opted in: 1 to 100 rows per call, with a result per row. It has its own rate bucket so a backfill never starves live checkouts.

batch
POST /v1/partners/enrolments/batch
X-Dalel-Idempotency-Key: backfill-2026-10-29-part-1

{ "rows": [ { …enrolment… }, { …enrolment… } ] }   // 1 to 100 rows

// 200 — per-row results; one bad row never sinks the batch
{
  "success": true,
  "data": {
    "batch_id": "bat_…",
    "total": 2,
    "accepted": 1,
    "already_registered": 1,
    "rejected": 0,
    "results": [
      { "index": 0, "external_customer_id": "SAH-00412", "result": "accepted", "enrolment_id": "enr_…", "created": true },
      { "index": 1, "external_customer_id": "SAH-00413", "result": "already_registered", "enrolment_id": "enr_…" }
    ]
  }
}

Read & withdraw

We never return the owner’s name, phone or email, only status and stage. Withdraw means the customer took back consent with you: before activation we erase their data at once; after it, only your attribution and future commission end.

GET / withdraw
GET  /v1/partners/enrolments?status=invited&updated_since=2026-10-01T00:00:00Z&limit=50&cursor=enr_…
GET  /v1/partners/enrolments/{enrolment_id}
GET  /v1/partners/enrolments/batches/{batch_id}
POST /v1/partners/enrolments/{enrolment_id}/withdraw

// list → { "data": [ …EnrolmentView… ], "next_cursor": "enr_…" | null }   (limit 1–100, default 50)
// another partner's id → 404 not_found (never 403)

Webhooks

Every webhook is a POST signed the same way with your subscription secret, and carries X-Dalel-Event, X-Dalel-Event-Id and X-Dalel-Delivery-Attempt. No event carries personal data.

Event
enrolment.received
enrolment.already_registered
invite.sent
invite.reminded
invite.failed
owner.activated
business.submitted
business.changes_requested
business.approved
business.published
commission.accrued
commission.reversed
payout.paid
invite.expired
invite.opted_out
enrolment.rejected
enrolment.withdrawn
enrolment.purged
batch.completed

Verifying the signature

Node · verify
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the exact bytes received. path: your endpoint's path + query.
export function verifyDalelWebhook(rawBody: Buffer, headers: Record<string, string>, path: string, secret: string) {
  const ts = headers['x-dalel-timestamp'];
  const nonce = headers['x-dalel-nonce'];
  const m = /^t=(\d+),v1=([0-9a-f]+)$/.exec(headers['x-dalel-signature'] ?? '');
  if (!m || m[1] !== ts) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;   // 5-minute window
  const bodySha = createHash('sha256').update(rawBody).digest('hex');
  const expected = createHmac('sha256', secret)
    .update(`v1:${ts}:${nonce}:POST:${path}:${bodySha}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}
// Dedupe on X-Dalel-Event-Id; answer 2xx within 10 s, then do the work.

Retries

If we do not get a 2xx within 10 s we retry after: 5s → 30s → 2m → 10m → 1h → 6h → 24h, then the delivery is dead-lettered and you can replay it from the portal.

Errors

Every error carries a stable error_code and a request_id. Quote the request_id in any support ticket.

Error shape
{
  "success": false,
  "request_id": "req_…",
  "error_code": "invalid_signature",
  "message": "The HMAC does not match the canonical string Dalel computed.",
  "action": "Rebuild the canonical string from the exact bytes you send, the request path, and the same timestamp and nonce."
}
HTTPerror_code
400missing_idempotency_key
400unknown_version
401missing_headers
401invalid_timestamp
401timestamp_out_of_window
401invalid_signature_header
401invalid_key_format
401unknown_or_expired_key
401invalid_secret
401invalid_signature
403partner_not_active
403ip_not_allowed
404not_found
409nonce_replayed
409idempotency_fingerprint_mismatch
422validation_failed
422suppressed
429rate_limited
500nonce_store_error
503module_disabled
503feature_disabled
503live_mode_disabled

Sandbox magic values

Test keys only. Use phone +218 91 000 0xxx, or the email <outcome>@test.dalel.ly, to walk the scripted outcome with no real message sent.

PhoneOutcomeEvents
+218 91 000 0001activatedinvite.sent → owner.activated
+218 91 000 0002publishedinvite.sent → owner.activated → business.submitted → business.approved → business.published → commission.accrued
+218 91 000 0003expiredinvite.sent → invite.reminded ×3 → invite.expired
+218 91 000 0004notmeinvite.sent → enrolment.rejected
+218 91 000 0005registered200 already_registered, no events
+218 91 000 0006changes… business.changes_requested → business.submitted → business.approved
+218 91 000 0007rejected… business.submitted → business.changes_requested
+218 91 000 0008refunded… business.published → commission.accrued → commission.reversed
+218 91 000 0009smsfailinvite.failed → invite.sent
+218 91 000 0010optoutinvite.sent → invite.opted_out

Rate limits

BucketPer minutePer day
Enrol & reads12020,000
Batch1050

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Over the limit you get a 429 with Retry-After.

Versioning & deprecation

Versions are dated. Each key is pinned to the version current when it was created; override it per request with Dalel-Version. We announce a retirement at least 12 months ahead, and a deprecated version keeps working until its sunset, with these headers on every response:

RFC 9745 / RFC 8594
Deprecation: @1824768000
Sunset: Fri, 29 Oct 2027 00:00:00 GMT
Link: <https://dalel.ly/developers#changelog>; rel="deprecation"

An unknown version is a 400 unknown_version.

Trust & support

Availability

Our target is 99.9% a month for the Partner API, with planned maintenance announced 7 days ahead.

Security

  • TLS 1.2+ only, with HSTS.
  • Keys are stored hashed, shown once, rotatable, with an optional IP allowlist.
  • Least privilege, with an audit log of every sensitive action.
  • Request logs never store request bodies.
  • We notify you of any breach affecting your data within 72 hours of confirming it.

Data retention

DataKept for
Customer never activatedErased on day 51, or within 24 h on “not me”
API request logs (no bodies)90 days, then 1 year archived
Commission ledger10 years

Support

PriorityExampleFirst reply
P1Live API down1 hour, 24/7
P2Degraded, workaround exists4 hours
P3Integration question1 working day
P4Feature request3 working days

Working days are Sunday to Thursday, 09:00–17:00 Libya time. Open a ticket from the partner portal, or write to [email protected].

Changelog

VersionChange
2026-10-29First release of the enrolment API: single and batch enrolment, reads and withdraw, invite/activation/business events, and sandbox magic values.
Developers: the enrolment API · Dalel