تخطى إلى المحتوى

API

Meta Collective Ads API

Integrate your store or platform to create and manage ad campaigns programmatically.

v1.5.0 ● Live REST / JSON https://nour-ads.com/wp-json/mca/v1

Endpoints Overview

MethodEndpointDescription
GET/accountAccount balance & info
POST/campaignsCreate a new campaign (two modes)
GET/campaigns/{id}Get single campaign status
GET/campaignsList all campaigns with pagination

Client Contact & Partner Privacyالتواصل مع العملاء وخصوصية المنصات الشريكة

When a campaign requires direct contact with the end customer (Mode A — Advertise on Your Page), our ad manager reaches out using the whatsapp_number and telegram_username submitted in the API request.

عندما تتطلب الحملة التواصل المباشر مع العميل النهائي (النمط A — إعلان على صفحتك)، يتواصل مديرنا الإعلاني عبر رقم whatsapp_number واسم telegram_username المُرسَلَين في طلب الـ API.

Why we never contact clients using our brand name or logo

When setup requires WhatsApp or Telegram, our ad manager contacts the end customer using an account that does not display our platform name or logo. We deliberately avoid branded business profiles that would reveal us as a third-party provider.

Your customers stay with you. End clients are never asked to register on our platform, visit our website, or switch to our brand. From their perspective, the ad service is part of your store or platform. This keeps the client relationship with the merchant and ensures they continue ordering ads through your API — not directly from us.

  • Submit the end customer's real whatsapp_number and telegram_username in every Mode A request.
  • Tell your customers they may receive a setup message from a neutral account (no our-brand name or logo).
  • Payment, balance, campaign status, and renewals stay entirely on your platform — we operate in the background.
العربية لماذا لا نتواصل مع العملاء بحساب يحمل اسم منصتنا أو شعارنا؟

عندما يتطلب الإعداد التواصل عبر واتساب أو تيلغرام، يتواصل مديرنا الإعلاني مع العميل النهائي من حساب لا يحمل اسم منصتنا أو شعارنا. نتجنّد عمداً أي حساب رسمي أو تجاري يظهر علامتنا، حتى لا يكتشف العميل أن الخدمة مقدّمة من طرف ثالث.

عملاؤكم يبقون عندكم — لا يأتون إلينا مباشرة. العميل النهائي لا يُطلب منه التسجيل في منصتنا، ولا زيارة موقعنا، ولا الانتقال إلى علامتنا. من وجهة نظره، خدمة الإعلان جزء من متجركم أو منصتكم. هكذا تبقى العلاقة بين التاجر وعميله، ويستمر العميل بطلب الإعلانات عبر واجهة الـ API الخاصة بكم — وليس مباشرة منا.

  • أرسلوا رقم واتساب وتيلغرام العميل الحقيقي في كل طلب من النمط A.
  • أخبروا عملاءكم أن رسالة الإعداد قد تأتي من حساب محايد بدون اسم منصتنا أو شعارنا.
  • الدفع والرصيد وحالة الحملة وتجديد الإعلانات تبقى بالكامل على منصتكم — نحن نعمل في الخلفية فقط.

Mode B (Publish on Our Page) does not require customer WhatsApp/Telegram — we publish and boost the ad on our page using the provided text and media only.

النمط B (النشر على صفحتنا) لا يتطلب واتساب/تيلغرام للعميل — ننشر الإعلان ونروّجه على صفحتنا باستخدام النص والوسائط المُرسَلة فقط.

Campaign Statuses

Every campaign returns a machine-readable status code and a human-readable English status_label. Poll GET /campaigns/{id} to track progress.

Status CodeLabelDescription
pending_adminPending ReviewCampaign created and paid. Waiting for admin approval before setup begins.
in_progressIn ProgressAdmin accepted the campaign. The ad manager is setting it up (you may be contacted on WhatsApp/Telegram for Mode A).
approvedIn ProgressSame as in_progress. An older status code kept for backward compatibility — some old campaigns may still return approved instead of in_progress. Treat both identically. New campaigns use in_progress after admin approval.
activeActiveAd is live and running on Facebook/Instagram.
pausedPausedAd temporarily paused. Budget is not being spent.
completedCompletedCampaign finished — duration ended or budget fully spent.
rejectedRejectedCampaign rejected by admin. Contact support for details.

Typical flow: pending_admin → in_progress → active → completed

Supported Countries & Provinces

Use the ISO country code as the key in targeting.countries. Province values must be the exact province keys listed below, or "all" for the entire country.

"targeting": {
  "countries": {
    "SY": ["damascus", "aleppo"],
    "SA": ["all"]
  },
  "gender": "all",
  "age_min": 18,
  "age_max": 65
}

22 countries supported — quick codes:

SY Syria 14 provinces · use "all" for all ▸
damascus rural_damascus aleppo homs hama latakia tartus idlib daraa suwayda quneitra deir_ez_zor raqqa hasakah
SA Saudi Arabia 13 provinces · use "all" for all ▸
riyadh makkah madinah eastern asir qassim hail tabuk jazan najran bahah jouf northern
EG Egypt 26 provinces · use "all" for all ▸
cairo alexandria giza sharqia dakahlia beheira gharbia monufia qalyubia fayoum minya asyut sohag qena luxor aswan ismailia suez port_said damietta kafr_el_sheikh red_sea new_valley matrouh north_sinai south_sinai
AE United Arab Emirates 7 provinces · use "all" for all ▸
dubai abu_dhabi sharjah ajman rak fujairah uaq
IQ Iraq 12 provinces · use "all" for all ▸
baghdad basra nineveh erbil sulaymaniyah kirkuk najaf karbala anbar diyala wasit babil
JO Jordan 12 provinces · use "all" for all ▸
amman irbid zarqa balqa madaba karak maan tafilah ajloun jerash mafraq aqaba
LB Lebanon 8 provinces · use "all" for all ▸
beirut mount_lebanon north south bekaa nabatieh akkar baalbek
KW Kuwait 6 provinces · use "all" for all ▸
capital hawalli farwaniya ahmadi jahra mubarak
QA Qatar 7 provinces · use "all" for all ▸
doha rayyan wakrah khor shamal daayen ummsalal
BH Bahrain 4 provinces · use "all" for all ▸
capital muharraq northern southern
OM Oman 8 provinces · use "all" for all ▸
muscat dhofar batinah dakhiliyah sharqiyah dhahirah buraimi musandam
PS Palestine 15 provinces · use "all" for all ▸
jerusalem ramallah nablus hebron bethlehem jenin tulkarm qalqilya salfit tubas gaza north_gaza central_gaza khan_yunis rafah
MA Morocco 16 provinces · use "all" for all ▸
casablanca rabat fes marrakech tangier agadir oujda kenitra meknes safi el_jadida beni_mellal tetouan nador laayoune dakhla
DZ Algeria 32 provinces · use "all" for all ▸
algiers oran constantine annaba blida setif batna djelfa sidi_bel_abbes biskra bejaia skikda tiaret tlemcen mostaganem msila mascara ouargla guelma relizane saida laghouat tipaza medea jijel khenchela mila ain_defla naama ghardaia tebessa bechar
TN Tunisia 24 provinces · use "all" for all ▸
tunis ariana ben_arous manouba nabeul zaghouan bizerte beja jendouba kef siliana kairouan kasserine sousse monastir mahdia sfax gafsa tozeur kebili gabes medenine tataouine sidi_bouzid
LY Libya 12 provinces · use "all" for all ▸
tripoli benghazi misrata zawiya bayda sabha derna tobruk sirte ghat kufra murzuq
SD Sudan 16 provinces · use "all" for all ▸
khartoum north_kordofan south_kordofan north_darfur south_darfur west_darfur east_darfur central_darfur red_sea kassala gedaref blue_nile white_nile sennar gezira river_nile
YE Yemen 16 provinces · use "all" for all ▸
sanaa aden taiz hodeidah ibb dhamar hadramaut marib hajjah amran lahj abyan shabwah mahwit raymah jawf
MR Mauritania 8 provinces · use "all" for all ▸
nouakchott nouadhibou rosso kaedi atar zouerate kiffa selibaby
SO Somalia 7 provinces · use "all" for all ▸
banadir puntland somaliland jubaland south_west hirshabelle galmudug
DJ Djibouti 6 provinces · use "all" for all ▸
djibouti_city ali_sabieh dikhil tadjourah obock arta
KM Comoros 3 provinces · use "all" for all ▸
ngazidja anjouan moheli

Authentication

All requests require a Bearer token. Generate yours above, then pass it in every request:

Authorization: Bearer mca_live_YOUR_TOKEN_HERE

Alternative: X-MCA-API-Key: mca_live_YOUR_TOKEN_HERE

Base URL:

https://nour-ads.com/wp-json/mca/v1

All requests and responses use JSON. Set Content-Type: application/json on POST requests. Use Idempotency-Key header on POST /campaigns to prevent duplicate charges on retry.

GET /account
Account Balance & Info ▼

Returns your current balance, account details, and linked user info.

Code Examples

cURL PHP JavaScript
curl -X GET "https://nour-ads.com/wp-json/mca/v1/account" \
  -H "Authorization: Bearer mca_live_YOUR_TOKEN"
$ch = curl_init("https://nour-ads.com/wp-json/mca/v1/account");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer mca_live_YOUR_TOKEN'],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://nour-ads.com/wp-json/mca/v1/account', {
  headers: { 'Authorization': 'Bearer mca_live_YOUR_TOKEN' }
});
const { data } = await res.json();

Example Request

GET https://nour-ads.com/wp-json/mca/v1/account HTTP/1.1
Authorization: Bearer mca_live_YOUR_TOKEN
Accept: application/json

Example Response

● 200 OK
{
  "success": true,
  "data": {
    "client": {
      "id": 3,
      "name": "My Store — API Client",
      "slug": "my-store-api",
      "token_prefix": "mca_live_abc123"
    },
    "user": {
      "id": 17,
      "email": "owner@mystore.com",
      "name": "Store Owner"
    },
    "balance": {
      "amount": 250.00,
      "currency": "USD"
    }
  }
}
POST /campaigns
Create Campaign ▼

Creates a campaign and deducts the balance immediately. Two modes are available — choose by setting content_type.

Mode A Advertise on Your Page

The advertiser wants to run ads from their own Facebook/Instagram page. Our ad manager will contact them via WhatsApp or Telegram to complete setup. See Client Contact & Partner Privacy — contact is made from an account with no our-brand name or logo, so end customers stay with your platform and never come to us directly.

يريد المعلن تشغيل إعلانات من صفحته على فيسبوك/إنستغرام. سيتواصل مديرنا عبر واتساب أو تيلغرام لإتمام الإعداد. راجع التواصل مع العملاء وخصوصية الشركاء — التواصل يتم من حساب لا يحمل اسم منصتنا أو شعارنا، ليبقى العميل عند التاجر ولا يأتي إلينا مباشرة.

ملاحظة: النمط A لا يتطلب إرسال صورة أو فيdeo عبر الـ API — المدير يتواصل مع العميل لإعداد الإعلان.

Parameters

NameTypeDescription
content_typestringoptionalSet to manager_setup (default). Our manager handles everything.
platformstringrequiredfacebook | instagram | both
goalstringoptionalpost_promotion (default) | engagement | reach | traffic | messages | conversions | video_views | brand_awareness
budget_dailynumberrequiredDaily budget when platform ≠ both. Min: 2
budget_daily_fbnumberconditionalFacebook daily budget — required when platform = both
budget_daily_ignumberconditionalInstagram daily budget — required when platform = both
duration_daysintegerrequiredCampaign length in days (1–30)
whatsapp_numberstringrequiredEnd customer's WhatsApp with country code, e.g. +966501234567. Contact is from an account without our platform name or logo — see privacy note.واتساب العميل النهائي مع رمز الدولة. التواصل من حساب لا يحمل اسم منصتنا أو شعارنا — راجع ملاحظة الخصوصية.
telegram_usernamestringrequiredEnd customer's Telegram handle without @, e.g. my_handle. Setup messages come from a neutral account — no our-brand name or logo — so the client stays with your merchant.اسم مستخدم تيلغرام العميل بدون @. رسائل الإعداد من حساب محايد بدون اسم منصتنا أو شعارنا، ليبقى العميل عند التاجر.
targetingobjectoptionalGeo targeting. See Supported Countries & Provinces. Example: { "countries":{"SY":["damascus"]}, "gender":"all", "age_min":18, "age_max":65 }
titlestringoptionalCampaign title (auto-generated if omitted)

Code Examples

cURL PHP JavaScript
# Mode A — Advertise on Your Page
curl -X POST "https://nour-ads.com/wp-json/mca/v1/campaigns" \
  -H "Authorization: Bearer mca_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "content_type": "manager_setup",
    "platform": "facebook",
    "goal": "post_promotion",
    "budget_daily": 10,
    "duration_days": 7,
    "whatsapp_number": "+966501234567",
    "telegram_username": "my_handle",
    "targeting": {
      "countries": { "SA": ["all"], "AE": ["all"] },
      "gender": "all",
      "age_min": 18,
      "age_max": 45
    }
  }'
$payload = [
  'content_type'      => 'manager_setup',
  'platform'          => 'facebook',
  'goal'              => 'post_promotion',
  'budget_daily'      => 10,
  'duration_days'     => 7,
  'whatsapp_number'   => '+966501234567',
  'telegram_username' => 'my_handle',
  'targeting'         => [
    'countries' => ['SA' => ['all'], 'AE' => ['all']],
    'gender'    => 'all',
    'age_min'   => 18,
    'age_max'   => 45,
  ],
];
$ch = curl_init("https://nour-ads.com/wp-json/mca/v1/campaigns");
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer mca_live_YOUR_TOKEN',
    'Content-Type: application/json',
    'Idempotency-Key: order-12345',
  ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://nour-ads.com/wp-json/mca/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mca_live_YOUR_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-12345'
  },
  body: JSON.stringify({
    content_type: 'manager_setup',
    platform: 'facebook',
    goal: 'post_promotion',
    budget_daily: 10,
    duration_days: 7,
    whatsapp_number: '+966501234567',
    telegram_username: 'my_handle',
    targeting: {
      countries: { SA: ['all'], AE: ['all'] },
      gender: 'all', age_min: 18, age_max: 45
    }
  })
});
const { data } = await res.json();

Example Request

POST https://nour-ads.com/wp-json/mca/v1/campaigns
Content-Type: application/json
Authorization: Bearer mca_live_YOUR_TOKEN
Idempotency-Key: order-12345

{
  "content_type": "manager_setup",
  "platform": "facebook",
  "goal": "post_promotion",
  "budget_daily": 10,
  "duration_days": 7,
  "whatsapp_number": "+966501234567",
  "telegram_username": "my_handle",
  "targeting": {
    "countries": { "SA": ["all"], "AE": ["all"] },
    "gender": "all",
    "age_min": 18,
    "age_max": 45
  }
}

Example Response

● 201 Created
{
  "success": true,
  "data": {
    "id": 57,
    "message": "Campaign submitted for review.",
    "charged": 80.50,
    "campaign_mode": "your_page",
    "content_type": "manager_setup"
  }
}
Mode B Publish on Our Page

We publish the ad on our platform's Facebook page and boost it. No Facebook page or admin access required from the advertiser — just provide ad text and media.

ننشر الإعلان على صفحتنا في فيسبوك ونروّجه. لا حاجة لصفحة فيسبوك من المعلن — يكفي نص الإعلان وملف الوسائط.

How to send images & video (URLs — not file upload)

The API accepts public HTTPS links in the assets array — you do not send binary files inside POST /campaigns. Upload the file to your own server, CDN, or storage first, then pass the URL.

Workflow: 1) Upload image/video on your platform → 2) Get a public URL → 3) Include it in assets when creating the campaign.

// Image only
"assets": [
  { "url": "https://yourstore.com/media/banner.jpg", "type": "image" }
]

// Video (MP4)
"assets": [
  { "url": "https://yourstore.com/media/promo.mp4", "type": "video" }
]

// Multiple files (up to 10)
"assets": [
  { "url": "https://yourstore.com/media/photo1.jpg", "type": "image" },
  { "url": "https://yourstore.com/media/photo2.png", "type": "image" }
]

// Shorthand — plain URL string defaults to type "image"
"assets": [ "https://yourstore.com/media/banner.jpg" ]
  • Images: JPG, PNG, GIF, WEBP — recommended max 5 MB per file
  • Video: MP4 — recommended max 50 MB
  • URL must be publicly accessible via HTTPS (no login required)
  • Max assets: 10 per campaign
العربية كيف ترسل الصورة أو الفيديو؟ (روابط — وليس رفع ملف مباشر)

الـ API يقبل روابط HTTPS عامة في حقل assets — لا ترسل الملف نفسه داخل طلب POST /campaigns. ارفع الصورة أو الفيديو أولاً على سيرفركم أو CDN أو تخزينكم، ثم أرسل الرابط.

الخطوات: 1) رفع الملف على منصتكم → 2) الحصول على رابط عام → 3) إرسال الرابط في assets عند إنشاء الحملة.

  • صور: JPG, PNG, GIF, WEBP — يُفضّل حتى 5 MB
  • فيديو: MP4 — يُفضّل حتى 50 MB
  • الرابط يجب أن يكون عاماً ومتاحاً عبر HTTPS (بدون تسجيل دخول)
  • الحد الأقصى: 10 ملفات لكل حملة

Parameters

NameTypeDescription
content_typestringrequiredMust be page_publish
platformstringrequiredfacebook | instagram | both
goalstringoptionalpost_promotion (default) | engagement | reach | traffic | …
budget_dailynumberrequiredDaily ad budget. Min: 2
budget_daily_fbnumberconditionalRequired when platform = both
budget_daily_ignumberconditionalRequired when platform = both
duration_daysintegerrequiredCampaign length in days (1–30)
page_ad_textstringrequiredThe ad copy text to publish on our page
assetsarrayrequiredPublic HTTPS URLs of media — see Images & Video guide. Each item: { "url":"https://…", "type":"image"|"video" } or a plain URL string (treated as image). Min 1, max 10.روابط HTTPS عامة للوسائط — راجع دليل الصور والفيديو. كل عنصر: { "url":"https://…", "type":"image"|"video" } أو رابط نصي فقط. الحد الأدنى 1، الأقصى 10.
targetingobjectoptionalGeo targeting. See Supported Countries & Provinces. Example: { "countries":{"SY":["damascus"]}, "gender":"all", "age_min":18, "age_max":65 }
titlestringoptionalCampaign title (auto-generated if omitted)

Code Examples

cURL PHP JavaScript
# Mode B — Publish on Our Page
curl -X POST "https://nour-ads.com/wp-json/mca/v1/campaigns" \
  -H "Authorization: Bearer mca_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-67890" \
  -d '{
    "content_type": "page_publish",
    "platform": "facebook",
    "goal": "engagement",
    "budget_daily": 15,
    "duration_days": 5,
    "page_ad_text": "Big summer sale — up to 70% off! Shop now.",
    "assets": [
      { "url": "https://mystore.com/images/banner.jpg", "type": "image" }
    ],
    "targeting": {
      "countries": { "SA": ["all"], "KW": ["all"] },
      "gender": "all",
      "age_min": 20,
      "age_max": 50
    }
  }'
$payload = [
  'content_type' => 'page_publish',
  'platform'     => 'facebook',
  'goal'         => 'engagement',
  'budget_daily' => 15,
  'duration_days'=> 5,
  'page_ad_text' => 'Big summer sale — up to 70% off! Shop now.',
  'assets'       => [
    ['url' => 'https://mystore.com/images/banner.jpg', 'type' => 'image'],
  ],
  'targeting'    => [
    'countries' => ['SA' => ['all'], 'KW' => ['all']],
    'gender'    => 'all',
    'age_min'   => 20,
    'age_max'   => 50,
  ],
];
$ch = curl_init("https://nour-ads.com/wp-json/mca/v1/campaigns");
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'Authorization: Bearer mca_live_YOUR_TOKEN',
    'Content-Type: application/json',
    'Idempotency-Key: order-67890',
  ],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://nour-ads.com/wp-json/mca/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mca_live_YOUR_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-67890'
  },
  body: JSON.stringify({
    content_type: 'page_publish',
    platform: 'facebook',
    goal: 'engagement',
    budget_daily: 15,
    duration_days: 5,
    page_ad_text: 'Big summer sale — up to 70% off! Shop now.',
    assets: [
      { url: 'https://mystore.com/images/banner.jpg', type: 'image' }
    ],
    targeting: {
      countries: { SA: ['all'], KW: ['all'] },
      gender: 'all', age_min: 20, age_max: 50
    }
  })
});
const { data } = await res.json();

Example Request

POST https://nour-ads.com/wp-json/mca/v1/campaigns
Content-Type: application/json
Authorization: Bearer mca_live_YOUR_TOKEN
Idempotency-Key: order-67890

{
  "content_type": "page_publish",
  "platform": "facebook",
  "goal": "engagement",
  "budget_daily": 15,
  "duration_days": 5,
  "page_ad_text": "Big summer sale — up to 70% off! Shop now.",
  "assets": [
    { "url": "https://mystore.com/images/banner.jpg", "type": "image" }
  ],
  "targeting": {
    "countries": { "SA": ["all"], "KW": ["all"] },
    "gender": "all",
    "age_min": 20,
    "age_max": 50
  }
}

Example Response

● 201 Created
{
  "success": true,
  "data": {
    "id": 58,
    "message": "Campaign submitted for review.",
    "charged": 75.00,
    "campaign_mode": "our_page",
    "content_type": "page_publish"
  }
}
GET /campaigns/{id}
Campaign Status ▼

Returns full details and live stats for a single campaign.

Parameters

NameTypeDescription
idintegerrequiredCampaign ID (path parameter)

Code Examples

cURL PHP JavaScript
curl -X GET "https://nour-ads.com/wp-json/mca/v1/campaigns/57" \
  -H "Authorization: Bearer mca_live_YOUR_TOKEN"
$ch = curl_init("https://nour-ads.com/wp-json/mca/v1/campaigns/57");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer mca_live_YOUR_TOKEN'],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://nour-ads.com/wp-json/mca/v1/campaigns/57', {
  headers: { 'Authorization': 'Bearer mca_live_YOUR_TOKEN' }
});
const { data } = await res.json();

Example Request

GET https://nour-ads.com/wp-json/mca/v1/campaigns/57 HTTP/1.1
Authorization: Bearer mca_live_YOUR_TOKEN
Accept: application/json

Example Response

● 200 OK
{
  "success": true,
  "data": {
    "id": 57,
    "title": "Summer Sale Campaign",
    "status": "active",
    "status_label": "Active",
    "campaign_mode": "your_page",
    "platform": "facebook",
    "goal": "post_promotion",
    "content_type": "manager_setup",
    "budget_total": 70.00,
    "budget_daily": 10.00,
    "budget_daily_fb": 10.00,
    "budget_daily_ig": 0,
    "budget_charged": 80.50,
    "budget_remaining": 65.00,
    "duration_days": 7,
    "currency": "USD",
    "total_spent": 5.00,
    "created_at": "2026-06-20 10:30:00",
    "updated_at": "2026-06-21 08:15:00",
    "start_date": "2026-06-21 00:00:00",
    "end_date": "2026-06-28 00:00:00"
  }
}

See Campaign Statuses for all possible status values.

GET /campaigns
List All Campaigns ▼

Returns a paginated list of all your campaigns with filtering by status.

Query Parameters

NameTypeDescription
pageintegeroptionalPage number (default: 1)
per_pageintegeroptionalResults per page (default: 20, max: 50)
statusstringoptionalpending_admin | in_progress | active | completed | rejected

Code Examples

cURL PHP JavaScript
curl -X GET "https://nour-ads.com/wp-json/mca/v1/campaigns?page=1&per_page=10&status=active" \
  -H "Authorization: Bearer mca_live_YOUR_TOKEN"
$ch = curl_init("https://nour-ads.com/wp-json/mca/v1/campaigns?page=1&per_page=10&status=active");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer mca_live_YOUR_TOKEN'],
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
const res = await fetch('https://nour-ads.com/wp-json/mca/v1/campaigns?page=1&per_page=10&status=active', {
  headers: { 'Authorization': 'Bearer mca_live_YOUR_TOKEN' }
});
const { data, meta } = await res.json();

Example Request

GET https://nour-ads.com/wp-json/mca/v1/campaigns?page=1&per_page=10&status=active HTTP/1.1
Authorization: Bearer mca_live_YOUR_TOKEN
Accept: application/json

Example Response

● 200 OK
{
  "success": true,
  "data": [
    {
      "id": 42,
      "title": "Summer Sale",
      "status": "active",
      "status_label": "Active",
      "campaign_mode": "your_page",
      "platform": "facebook",
      "goal": "post_promotion",
      "content_type": "manager_setup",
      "budget_total": 70.00,
      "budget_daily": 10.00,
      "budget_daily_fb": 10.00,
      "budget_daily_ig": 0,
      "budget_charged": 80.50,
      "budget_remaining": 35.00,
      "duration_days": 7,
      "currency": "USD",
      "total_spent": 35.00,
      "created_at": "2026-06-20 10:30:00",
      "updated_at": "2026-06-24 14:00:00",
      "start_date": "2026-06-21 00:00:00",
      "end_date": ""
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 14,
    "pages": 2
  }
}

Error Codes

HTTPCodeMeaning
401unauthorizedMissing or invalid API token.
403forbiddenToken suspended or missing permission.
400invalid_platformMust be facebook, instagram, or both.
400budget_too_lowDaily budget below minimum (2.00).
400insufficient_balanceAccount balance too low. See details.balance & details.required.
400duplicate_requestIdempotency key already used.
404not_foundCampaign not found or doesn't belong to your account.
429rate_limitedToo many requests (default 60/min).
تيليجرام