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.
| Environment | Key | What happens |
|---|---|---|
| Sandbox | dlpk_test_… | No real messages; magic numbers script the outcome. |
| Live | dlpk_live_… | Enabled once the go-live checklist in the partner portal is green. |
Quickstart
- Create a sandbox key
Partner portal › Keys & webhooks › New key. The secret is shown once; keep it in your secrets store.
- Sign the request
HMAC-SHA256 with the secret half of your key over:
v1:{timestamp}:{nonce}:{METHOD}:{path}:{sha256_hex(raw_body)}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}') - Enrol a customer
In the sandbox, +218 91 000 0001 walks through to activation.
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" - Receive the webhook
Verify X-Dalel-Signature and answer 2xx within 10 s. We retry after 5s → 30s → 2m → 10m → 1h → 6h → 24h.
- 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.
| Header | Value |
|---|---|
X-Dalel-Partner-Key | The full key: prefix, a dot, then the secret |
X-Dalel-Timestamp | Unix epoch seconds (integer) |
X-Dalel-Nonce | Random value, up to 128 characters |
X-Dalel-Signature | t={timestamp},v1={hex} |
X-Dalel-Idempotency-Key | Required on writes; reuse it when you retry |
Dalel-Version | 2026-10-29 |
The signed string: v1:{timestamp}:{nonce}:{METHOD}:{path}:{sha256_hex(raw_body)}
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.
{
"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" }
}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"
}
}| Status | Meaning |
|---|---|
| 202 | New enrolment created |
| 200 | Existing enrolment, or already on Dalel (already_registered: we message nobody, no commission) |
| 422 | validation_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.
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 /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
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.
{
"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."
}| HTTP | error_code |
|---|---|
| 400 | missing_idempotency_key |
| 400 | unknown_version |
| 401 | missing_headers |
| 401 | invalid_timestamp |
| 401 | timestamp_out_of_window |
| 401 | invalid_signature_header |
| 401 | invalid_key_format |
| 401 | unknown_or_expired_key |
| 401 | invalid_secret |
| 401 | invalid_signature |
| 403 | partner_not_active |
| 403 | ip_not_allowed |
| 404 | not_found |
| 409 | nonce_replayed |
| 409 | idempotency_fingerprint_mismatch |
| 422 | validation_failed |
| 422 | suppressed |
| 429 | rate_limited |
| 500 | nonce_store_error |
| 503 | module_disabled |
| 503 | feature_disabled |
| 503 | live_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.
| Phone | Outcome | Events |
|---|---|---|
| +218 91 000 0001 | activated | invite.sent → owner.activated |
| +218 91 000 0002 | published | invite.sent → owner.activated → business.submitted → business.approved → business.published → commission.accrued |
| +218 91 000 0003 | expired | invite.sent → invite.reminded ×3 → invite.expired |
| +218 91 000 0004 | notme | invite.sent → enrolment.rejected |
| +218 91 000 0005 | registered | 200 already_registered, no events |
| +218 91 000 0006 | changes | … business.changes_requested → business.submitted → business.approved |
| +218 91 000 0007 | rejected | … business.submitted → business.changes_requested |
| +218 91 000 0008 | refunded | … business.published → commission.accrued → commission.reversed |
| +218 91 000 0009 | smsfail | invite.failed → invite.sent |
| +218 91 000 0010 | optout | invite.sent → invite.opted_out |
Rate limits
| Bucket | Per minute | Per day |
|---|---|---|
| Enrol & reads | 120 | 20,000 |
| Batch | 10 | 50 |
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:
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
| Data | Kept for |
|---|---|
| Customer never activated | Erased on day 51, or within 24 h on “not me” |
| API request logs (no bodies) | 90 days, then 1 year archived |
| Commission ledger | 10 years |
Support
| Priority | Example | First reply |
|---|---|---|
| P1 | Live API down | 1 hour, 24/7 |
| P2 | Degraded, workaround exists | 4 hours |
| P3 | Integration question | 1 working day |
| P4 | Feature request | 3 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
| Version | Change |
|---|---|
| 2026-10-29 | First release of the enrolment API: single and batch enrolment, reads and withdraw, invite/activation/business events, and sandbox magic values. |