{ "openapi": "3.1.0", "info": { "title": "DreamCheck API", "version": "1.0.0", "summary": "Bangladesh courier fraud-check API", "termsOfService": "https://www.check.dreamlanceit.com/terms", "license": { "name": "Proprietary — see terms", "url": "https://www.check.dreamlanceit.com/terms" }, "description": "বাংলাদেশি মোবাইল নম্বরের কুরিয়ার ডেলিভারি হিস্ট্রি, সফলতার হার ও ঝুঁকি।\n\nLook up a Bangladeshi customer's courier delivery history (Steadfast, Pathao, RedX, Paperfly, Carrybee), success ratio and risk level; report fraudulent numbers; and contribute delivery outcomes.\n\nTest keys (`dc_test_…`) return deterministic sample data, cost nothing and never write data." }, "servers": [ { "url": "https://www.check.dreamlanceit.com/api/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Account", "description": "Key and plan information" }, { "name": "Check", "description": "Customer risk lookups (scope: check)" }, { "name": "Contribute", "description": "Send reports and delivery outcomes (scopes: report, deliveries)" } ], "paths": { "/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Key, plan and remaining quota", "description": "সংযোগ পরীক্ষার জন্য ব্যবহার করুন — কোনো চেক খরচ হয় না।", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Me" } } }, "example": { "status": true, "data": { "name": "Demo Shop BD", "email": "shop@example.com", "plan": "Business", "plan_ends_at": "2026-10-30T00:00:00+06:00", "daily_limit": 500, "remaining_today": 482, "features": { "api": true, "bulk": true }, "key": { "name": "My app", "mode": "live", "scopes": [ "check", "report", "deliveries" ] }, "app_url": "https://www.check.dreamlanceit.com/app" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/check": { "get": { "tags": [ "Check" ], "operationId": "checkPhone", "summary": "Check one phone number", "description": "নম্বরের সব কুরিয়ারের হিস্ট্রি, সফলতার হার, ঝুঁকি। প্রতি কলে দৈনিক লিমিট থেকে ১টি কাটে (লাইভ key)। যেকোনো ফরম্যাট চলে: 01…, +8801…, 8801…", "parameters": [ { "name": "phone", "in": "query", "required": true, "schema": { "type": "string" }, "example": "01712345678" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/CheckResult" }, "remaining_today": { "type": [ "integer", "null" ], "description": "null = unlimited or test mode" }, "mode": { "type": "string", "enum": [ "live", "test" ] } } }, "example": { "status": true, "data": { "phone": "01712345678", "summary": { "total": 20, "delivered": 14, "cancelled": 6, "success_ratio": 70, "reports": 0, "courier_reports": 0, "couriers_with_data": 4 }, "risk": { "level": "medium", "label": "সতর্কতা", "advice": "পাঠানোর আগে কল করে কনফার্ম করুন", "color": "amber" }, "couriers": { "steadfast": { "courier": "steadfast", "status": "ok", "total": 10, "delivered": 7, "cancelled": 3, "success_ratio": 70, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "steadfast", "source_label": "Steadfast", "also_from": [] }, "pathao": { "courier": "pathao", "status": "ok", "total": 6, "delivered": 4, "cancelled": 2, "success_ratio": 66.7000000000000028421709430404007434844970703125, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "pathao", "source_label": "Pathao", "also_from": [] }, "redx": { "courier": "redx", "status": "ok", "total": 4, "delivered": 3, "cancelled": 1, "success_ratio": 75, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "fraudbd", "source_label": "FraudBD", "also_from": [] }, "paperfly": { "courier": "paperfly", "status": "ok", "total": 0, "delivered": 0, "cancelled": 0, "success_ratio": null, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "fraudbd", "source_label": "FraudBD", "also_from": [] }, "carrybee": { "courier": "carrybee", "status": "not_configured", "total": null, "delivered": null, "cancelled": null, "success_ratio": null, "rating": null, "fraud_reports": 0, "message": "কোনো ডেটা সোর্স যুক্ত নেই", "cached": false, "source": null, "source_label": null, "also_from": [] } }, "sources": { "steadfast": { "label": "Steadfast", "status": "ok", "message": null, "cached": false } }, "community": { "delivered": 0, "returned": 0, "sellers": 0 }, "checked_at": "2026-09-30T10:15:00+06:00" }, "remaining_today": 481, "mode": "live" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Check" ], "operationId": "checkPhonePost", "summary": "Check one phone number (JSON body)", "description": "GET-এর মতোই, শুধু নম্বর JSON body-তে।", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" } } }, "example": { "phone": "01712345678" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/CheckResult" }, "remaining_today": { "type": [ "integer", "null" ], "description": "null = unlimited or test mode" }, "mode": { "type": "string", "enum": [ "live", "test" ] } } }, "example": { "status": true, "data": { "phone": "01712345678", "summary": { "total": 20, "delivered": 14, "cancelled": 6, "success_ratio": 70, "reports": 0, "courier_reports": 0, "couriers_with_data": 4 }, "risk": { "level": "medium", "label": "সতর্কতা", "advice": "পাঠানোর আগে কল করে কনফার্ম করুন", "color": "amber" }, "couriers": { "steadfast": { "courier": "steadfast", "status": "ok", "total": 10, "delivered": 7, "cancelled": 3, "success_ratio": 70, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "steadfast", "source_label": "Steadfast", "also_from": [] }, "pathao": { "courier": "pathao", "status": "ok", "total": 6, "delivered": 4, "cancelled": 2, "success_ratio": 66.7000000000000028421709430404007434844970703125, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "pathao", "source_label": "Pathao", "also_from": [] }, "redx": { "courier": "redx", "status": "ok", "total": 4, "delivered": 3, "cancelled": 1, "success_ratio": 75, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "fraudbd", "source_label": "FraudBD", "also_from": [] }, "paperfly": { "courier": "paperfly", "status": "ok", "total": 0, "delivered": 0, "cancelled": 0, "success_ratio": null, "rating": null, "fraud_reports": 0, "message": null, "cached": false, "source": "fraudbd", "source_label": "FraudBD", "also_from": [] }, "carrybee": { "courier": "carrybee", "status": "not_configured", "total": null, "delivered": null, "cancelled": null, "success_ratio": null, "rating": null, "fraud_reports": 0, "message": "কোনো ডেটা সোর্স যুক্ত নেই", "cached": false, "source": null, "source_label": null, "also_from": [] } }, "sources": { "steadfast": { "label": "Steadfast", "status": "ok", "message": null, "cached": false } }, "community": { "delivered": 0, "returned": 0, "sellers": 0 }, "checked_at": "2026-09-30T10:15:00+06:00" }, "remaining_today": 481, "mode": "live" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk-check": { "post": { "tags": [ "Check" ], "operationId": "bulkCheck", "summary": "Check up to 25 numbers", "description": "একসাথে অনেক নম্বর। প্রতিটা সঠিক নম্বরের জন্য ১টি চেক কাটে; ভুল নম্বর `invalid`-এ ফেরত আসে। প্ল্যানে বাল্ক অ্যাক্সেস লাগে। রেট লিমিট: মিনিটে ১০টি রিকোয়েস্ট।", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phones" ], "properties": { "phones": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "string" } } } }, "example": { "phones": [ "01712345678", "+8801812345670", "abc" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BulkItem" } }, "invalid": { "type": "array", "items": { "type": "string" } }, "remaining_today": { "type": [ "integer", "null" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] } } }, "example": { "status": true, "data": { "01712345678": { "risk": "medium", "risk_label": "সতর্কতা", "success_ratio": 70, "total": 20, "delivered": 14, "cancelled": 6, "reports": 0, "couriers": { "steadfast": { "total": 10, "delivered": 7, "cancelled": 3, "rating": null, "source": "steadfast" } } } }, "invalid": [ "abc" ], "remaining_today": 480, "mode": "live" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk-jobs": { "post": { "tags": [ "Check" ], "operationId": "createBulkJob", "summary": "Start a background bulk check (up to 200 numbers)", "description": "বড় তালিকার জন্য। সাথে সাথে `202` ও job id ফেরত আসে; চেক ব্যাকগ্রাউন্ডে চলে। ফলাফল পেতে `GET /bulk-jobs/{id}` পোল করুন অথবা `bulk.completed` webhook নিন। টেস্ট key-তে সাথে সাথে শেষ হয়।", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phones" ], "properties": { "phones": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string" } } } }, "example": { "phones": [ "01712345678", "01812345670", "01912345675" ] } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BulkJob" } } }, "example": { "status": true, "data": { "id": "9b2f6c1e-4d7a-4a57-9a51-2f1f0f3c8e21", "status": "queued", "mode": "live", "total": 3, "processed": 0, "invalid": [], "created_at": "2026-09-30T10:15:00+06:00", "url": "https://www.check.dreamlanceit.com/api/v1/bulk-jobs/9b2f6c1e-4d7a-4a57-9a51-2f1f0f3c8e21" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/bulk-jobs/{id}": { "get": { "tags": [ "Check" ], "operationId": "getBulkJob", "summary": "Bulk job status and results", "description": "`status`: queued → running → done (বা failed)। `processed`/`total` দিয়ে অগ্রগতি দেখান। লিমিট শেষ হয়ে গেলে বাকি নম্বরে `skipped: daily_limit_reached` থাকে।", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/BulkJob" } } }, "example": { "status": true, "data": { "id": "9b2f6c1e-4d7a-4a57-9a51-2f1f0f3c8e21", "status": "done", "mode": "live", "total": 3, "processed": 3, "invalid": [], "created_at": "2026-09-30T10:15:00+06:00", "finished_at": "2026-09-30T10:15:09+06:00", "results": { "01712345678": { "risk": "low", "risk_label": "নিরাপদ", "advice": "নিশ্চিন্তে পার্সেল পাঠাতে পারেন", "success_ratio": 92.5, "total": 40, "delivered": 37, "cancelled": 3, "reports": 0, "couriers": { "steadfast": { "total": 25, "delivered": 23, "cancelled": 2, "rating": null, "source": "steadfast" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports": { "post": { "tags": [ "Contribute" ], "operationId": "reportPhone", "summary": "Report a fraudulent number", "description": "একই নম্বর আবার রিপোর্ট করলে আগের রিপোর্ট আপডেট হয়। মিথ্যা রিপোর্ট করলে অ্যাকাউন্ট বন্ধ হতে পারে।", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" }, "example": { "phone": "01712345678", "reason": "fake_order", "note": "৩ বার অর্ডার করে রিসিভ করেনি" } } } }, "responses": { "200": { "description": "Reported", "content": { "application/json": { "example": { "status": true, "message": "Reported", "mode": "live" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/deliveries": { "post": { "tags": [ "Contribute" ], "operationId": "pushDeliveries", "summary": "Send delivery outcomes (max 200)", "description": "আপনার অর্ডারের ডেলিভারি ফলাফল নেটওয়ার্কে পাঠান — সবার চেক আরও নির্ভুল হয়। `order_ref` দিয়ে idempotent: একই রেফারেন্স আবার পাঠালে আপডেট হয়, ডুপ্লিকেট হয় না। নাম-ঠিকানা পাঠাবেন না।", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "$ref": "#/components/schemas/DeliveryRecord" } } } }, "example": { "records": [ { "phone": "01712345678", "order_ref": "shop.com#1001", "outcome": "delivered", "courier": "steadfast", "amount": 1250 } ] } } } }, "responses": { "200": { "description": "Saved", "content": { "application/json": { "example": { "status": true, "saved": 1, "skipped": [], "mode": "live" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "phone.reported": { "post": { "summary": "phone.reported", "description": "আপনি আগে চেক করেছেন এমন নম্বর অন্য সেলার রিপোর্ট করলে। ২xx উত্তর দিলে সফল ধরা হয়; না দিলে ১মি, ৫মি, ১৫মি, ১ঘ, ৬ঘ পরে আবার চেষ্টা হয়।", "operationId": "webhookPhoneReported", "parameters": [ { "name": "X-DreamCheck-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event name" }, { "name": "X-DreamCheck-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique delivery id — use it to ignore duplicates" }, { "name": "X-DreamCheck-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "e3c9c1b0-0e1d-4d7e-8a31-5d2f7a9b1c44", "event": "phone.reported", "created_at": "2026-09-30T11:00:00+06:00", "livemode": true, "data": { "phone": "01712345678", "reason": "fake_order", "reason_label": "ভুয়া অর্ডার", "reported_at": "2026-09-30T11:00:00+06:00", "your_last_check_at": "2026-09-29T18:20:00+06:00" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds" } } } }, "bulk.completed": { "post": { "summary": "bulk.completed", "description": "ব্যাকগ্রাউন্ড বাল্ক চেক শেষ হলে। ২xx উত্তর দিলে সফল ধরা হয়; না দিলে ১মি, ৫মি, ১৫মি, ১ঘ, ৬ঘ পরে আবার চেষ্টা হয়।", "operationId": "webhookBulkCompleted", "parameters": [ { "name": "X-DreamCheck-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event name" }, { "name": "X-DreamCheck-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique delivery id — use it to ignore duplicates" }, { "name": "X-DreamCheck-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "e3c9c1b0-0e1d-4d7e-8a31-5d2f7a9b1c44", "event": "bulk.completed", "created_at": "2026-09-30T11:00:00+06:00", "livemode": true, "data": { "id": "9b2f6c1e-4d7a-4a57-9a51-2f1f0f3c8e21", "status": "done", "mode": "live", "total": 3, "processed": 3, "invalid": [], "results": { "01712345678": { "risk": "low", "success_ratio": 92.5 } } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds" } } } }, "plan.expiring": { "post": { "summary": "plan.expiring", "description": "প্ল্যানের মেয়াদ ৩ দিনের মধ্যে শেষ হলে। ২xx উত্তর দিলে সফল ধরা হয়; না দিলে ১মি, ৫মি, ১৫মি, ১ঘ, ৬ঘ পরে আবার চেষ্টা হয়।", "operationId": "webhookPlanExpiring", "parameters": [ { "name": "X-DreamCheck-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Event name" }, { "name": "X-DreamCheck-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique delivery id — use it to ignore duplicates" }, { "name": "X-DreamCheck-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "e3c9c1b0-0e1d-4d7e-8a31-5d2f7a9b1c44", "event": "plan.expiring", "created_at": "2026-09-30T11:00:00+06:00", "livemode": true, "data": { "plan": "Business", "ends_at": "2026-10-03T10:00:00+06:00", "renew_url": "https://www.check.dreamlanceit.com/billing" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer dc_live_… (or dc_test_…)" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "responses": { "Unauthorized": { "description": "Missing / invalid key (invalid_api_key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": false, "message": "API key নেই, ভুল অথবা বাতিল করা।", "error": { "code": "invalid_api_key" } } } } }, "Forbidden": { "description": "plan_required, scope_missing, bulk_not_in_plan, account_disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": false, "message": "এই key-তে এই কাজের অনুমতি (scope) নেই।", "error": { "code": "scope_missing", "required_scope": "report" } } } } }, "ValidationError": { "description": "invalid_phone or validation_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": false, "message": "রিকোয়েস্টের তথ্য সঠিক নয়।", "error": { "code": "validation_error", "fields": { "reason": [ "The selected reason is invalid." ] } } } } } }, "TooManyRequests": { "description": "daily_limit_reached or rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": false, "message": "আজকের চেক লিমিট শেষ।", "error": { "code": "daily_limit_reached", "limit": 500 } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "status", "message", "error" ], "properties": { "status": { "type": "boolean", "const": false }, "message": { "type": "string", "description": "Human-readable (Bangla)" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "plan_required", "scope_missing", "bulk_not_in_plan", "account_disabled", "invalid_phone", "validation_error", "daily_limit_reached", "rate_limited", "not_found", "method_not_allowed", "server_error" ] } }, "additionalProperties": true } } }, "Me": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "plan": { "type": "string" }, "plan_ends_at": { "type": [ "string", "null" ], "format": "date-time" }, "daily_limit": { "type": [ "integer", "null" ] }, "remaining_today": { "type": [ "integer", "null" ] }, "features": { "type": "object", "properties": { "api": { "type": "boolean" }, "bulk": { "type": "boolean" } } }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "check", "report", "deliveries" ] } } } }, "app_url": { "type": "string", "format": "uri" } } }, "Risk": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "new", "low", "medium", "high", "very_high" ] }, "label": { "type": "string", "description": "Bangla label, e.g. নিরাপদ" }, "advice": { "type": "string", "description": "What the seller should do (Bangla)" }, "color": { "type": "string" } } }, "Summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "delivered + cancelled" }, "delivered": { "type": "integer" }, "cancelled": { "type": "integer" }, "success_ratio": { "type": [ "number", "null" ], "description": "0–100, null when no history" }, "reports": { "type": "integer", "description": "Seller fraud reports" }, "courier_reports": { "type": "integer", "description": "Fraud reports held by couriers" }, "couriers_with_data": { "type": "integer" } } }, "CourierResult": { "type": "object", "properties": { "courier": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error", "not_configured" ] }, "total": { "type": [ "integer", "null" ] }, "delivered": { "type": [ "integer", "null" ] }, "cancelled": { "type": [ "integer", "null" ] }, "success_ratio": { "type": [ "number", "null" ] }, "rating": { "type": [ "string", "null" ], "description": "e.g. Pathao customer_rating when only a rating is available" }, "fraud_reports": { "type": "integer" }, "message": { "type": [ "string", "null" ] }, "cached": { "type": "boolean" }, "source": { "type": [ "string", "null" ], "description": "Data source key (steadfast, pathao, fraudbd, bdcourier, sample)" }, "source_label": { "type": [ "string", "null" ] }, "also_from": { "type": "array", "items": { "type": "string" } } } }, "CheckResult": { "type": "object", "properties": { "phone": { "type": "string", "description": "Normalized 01XXXXXXXXX" }, "summary": { "$ref": "#/components/schemas/Summary" }, "risk": { "$ref": "#/components/schemas/Risk" }, "couriers": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CourierResult" }, "description": "Keyed by courier: steadfast, pathao, redx, paperfly, carrybee" }, "sources": { "type": "object", "additionalProperties": { "type": "object" } }, "community": { "type": "object", "properties": { "delivered": { "type": "integer" }, "returned": { "type": "integer" }, "sellers": { "type": "integer" } } }, "checked_at": { "type": "string", "format": "date-time" }, "test_mode": { "type": "boolean", "description": "Present (true) only for test keys" } } }, "BulkItem": { "type": "object", "properties": { "risk": { "type": [ "string", "null" ], "enum": [ "new", "low", "medium", "high", "very_high", null ] }, "risk_label": { "type": "string" }, "advice": { "type": "string" }, "skipped": { "type": "string", "description": "Present when the number was not checked, e.g. daily_limit_reached" }, "success_ratio": { "type": [ "number", "null" ] }, "total": { "type": "integer" }, "delivered": { "type": "integer" }, "cancelled": { "type": "integer" }, "reports": { "type": "integer" }, "couriers": { "type": "object", "additionalProperties": { "type": "object" } } } }, "BulkJob": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "invalid": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time" }, "error": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "results": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/BulkItem" } } } }, "WebhookEvent": { "type": "object", "required": [ "id", "event", "created_at", "livemode", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string", "enum": [ "phone.reported", "bulk.completed", "plan.expiring", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" }, "data": { "type": "object" } } }, "ReportRequest": { "type": "object", "required": [ "phone", "reason" ], "properties": { "phone": { "type": "string" }, "reason": { "type": "string", "enum": [ "fake_order", "refused", "unreachable", "abusive", "other" ] }, "note": { "type": "string", "maxLength": 500 } } }, "DeliveryRecord": { "type": "object", "required": [ "phone", "order_ref", "outcome" ], "properties": { "phone": { "type": "string" }, "order_ref": { "type": "string", "maxLength": 100, "description": "Your unique order reference, e.g. shop.com#1001" }, "outcome": { "type": "string", "enum": [ "delivered", "returned", "cancelled" ] }, "courier": { "type": "string", "description": "steadfast, pathao, redx, paperfly, carrybee…" }, "amount": { "type": "number", "minimum": 0 }, "occurred_at": { "type": "string", "format": "date-time" } } } } } }