🔐 Authentication
All API requests require authentication using your license key or admin key.
License Key Authentication
For merchant endpoints (phone lookup, events, license verify):
Authorization: Bearer YOUR_LICENSE_KEY X-Country: MA
Admin Key Authentication
For admin endpoints (merchant management, manual blacklist):
X-Admin-Key: YOUR_ADMIN_KEY X-Country: MA
ℹ️ Note: All requests must include
X-Country: MA header. Currently, only Morocco (MA) is supported.
📱 Phone Lookup & Risk Scoring
POST
/v1/phone/lookup
Check a phone number's risk score, carrier information, and blacklist status.
Request Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer YOUR_LICENSE_KEY | Required |
X-Country | MA | Required |
Content-Type | application/json | Required |
Request Body
| Parameter | Type | Description | Required |
|---|---|---|---|
phone | string | Phone number (+212661234567 or 0661234567) | Required |
include_timeline | boolean | Include last 5 events for this phone | Optional |
Example Request
curl -X POST https://api.dpd.ma/v1/phone/lookup \
-H "Content-Type: application/json" \
-H "X-Country: MA" \
-H "Authorization: Bearer DPD-STARTER-TEST-002" \
-d '{
"phone": "+212661234567",
"include_timeline": true
}'Response
{
"ok": true,
"phone": "+212661234567",
"country": "MA",
"carrier": { "code": "IAM", "label": "Maroc Telecom" },
"risk_score": 8,
"is_blacklisted": false,
"blacklisted_reason": null,
"cache_ttl_seconds": 3600,
"timeline": [
{
"event_type": "DELIVERED",
"order_total": "299.50",
"currency": "MAD",
"region": "Casablanca",
"created_at": "2026-02-01T21:47:49.589Z"
}
]
}Risk Score Interpretation
| Score | Risk Level | Recommendation |
|---|---|---|
| 80-100 | ✅ Low Risk | Safe to proceed |
| 50-70 | ⚠️ Medium Risk | Verify before proceeding |
| 10-40 | 🚫 High Risk | Proceed with caution or reject |
📊 Submit Events
POST
/v1/phone/lookup (with event_type)
Report order outcomes to improve risk scoring accuracy.
Request Body (Additional Fields)
| Parameter | Type | Description | Required |
|---|---|---|---|
event_type | string | DELIVERED, PAID_ONLINE, REFUSED_COD, CANCELLED, NO_ANSWER, FRAUD_CONFIRMED | Optional |
context.order_total | number | Order amount | Optional |
context.currency | string | Currency code (MAD) | Optional |
context.region | string | Delivery region | Optional |
context.note | string | Additional notes | Optional |
Example Request
curl -X POST https://api.dpd.ma/v1/phone/lookup \
-H "Content-Type: application/json" \
-H "X-Country: MA" \
-H "Authorization: Bearer DPD-STARTER-TEST-002" \
-d '{
"phone": "+212661234567",
"event_type": "DELIVERED",
"context": {
"order_total": 299.50,
"currency": "MAD",
"region": "Casablanca"
}
}'
✅ Best Practice: Submit events for all orders to improve scoring accuracy and help the entire merchant community.
🔑 License Verification
POST
/v1/license/verify
Verify your license status and check daily usage limits.
Request Body
| Parameter | Type | Description | Required |
|---|---|---|---|
site_url | string | Your registered website URL | Required |
email | string | Your registered email | Required |
⚙️ Admin Endpoints
ℹ️ Admin Only: These endpoints require
X-Admin-Key authentication.
❌ Error Codes
| Error Code | HTTP Status | Description |
|---|---|---|
LICENSE_MISSING | 401 | Missing Authorization Bearer token |
LICENSE_INVALID | 403 | Invalid or inactive license |
LICENSE_EXPIRED | 403 | Subscription expired, renewal required |
COUNTRY_NOT_ALLOWED | 403 | X-Country header must be MA |
DAILY_LIMIT_REACHED | 429 | Daily API usage limit exceeded |
INVALID_PAYLOAD | 400 | Request body validation failed |
ADMIN_UNAUTHORIZED | 401 | Missing or invalid X-Admin-Key |