API ng Kampanya ng Advertiser ng CPAlead: Lumikha at Pamahalaan ang mga Alok

Hinahayaan ng CPAlead Campaign API ang isang verified self-serve advertiser na gumamit ng code, AI agent, MCP server, o plugin para magtrabaho sa CPA, CPI, at CPC campaigns. Maaaring basahin ng isang awtorisadong client ang kasalukuyang campaign requirements, i-validate ang kumpletong campaign bago ito i-save, mag-upload ng creative, lumikha ng campaign, maglista at kumuha ng campaigns, mag-edit ng campaign na may version protection, at tahasang magsimula o mag-pause ng karapat-dapat na campaign.

Ito ang automation na kasama ng karaniwang advertiser dashboard. Kung gusto mo muna ng paliwanag na field-by-field tungkol sa mga campaign type, tracking, targeting, payouts, caps, funding, review, at launch, basahin ang How to Advertise on CPAlead in 2026: Add and Launch Your First Offer. Gamitin ang artikulong ito kapag handa ka nang isalin ang setup na iyon bilang structured JSON at kontroladong API actions.

Ano ang kaya ng Campaign API

Ang API ay hindi kasalukuyang nagbibigay ng archive, delete, bulk-create, o generic toggle operation. Ang archive o delete ay ginagawa sa dashboard workflow. Ang start at pause ay magkahiwalay na actions para makapaghiling ang tao o AI client ng malinaw na kumpirmasyon bago baguhin ang delivery.

Magkaiba ang Campaign API at Offer API Import

• Campaign API: Isang scoped bearer-token API na nagva-validate, lumilikha, nagbabasa, nag-e-edit, nagsisimula, at nagpapahinto ng mga campaign sa iyong advertiser account.
• Offer API Import: Isang hiwalay na advertiser-dashboard workflow na nagbabasa ng offers mula sa compatible na external feed at ina-map ang mga field nito papasok sa CPAlead.

Pinananatili ng Advertiser API Center ang mga tool na ito sa magkahiwalay na page. Mag-sign in, buksan ang Setup → API, at piliin ang tool na tumutugma sa iyong gawain. Gamitin ang Campaign API kapag ang sarili mong application, agent, MCP server, o plugin ay may hawak na offer data at kailangan ng istrukturadong paraan para magtrabaho sa CPAlead. Gamitin ang importer kapag dapat kumuha at i-map ng CPAlead ang isang sinusuportahang offer feed. Huwag bigyan ang isang integration ng mas malawak na token kaysa sa kailangan ng trabaho nito.

Gumawa ng Campaign API token

1. Mag-sign in sa isang verified self-serve advertiser account.
2. Buksan ang Setup → API, pagkatapos piliin ang Campaign API.
3. Bigyan ang token ng madaling makilalang pangalan, gaya ng “Campaign validator” o “My MCP agent.”
4. Pumili ng expiration. Inirerekomenda ang 48-hour option para sa AI setup; available din ang 30-day, 90-day, at 365-day na opsyon.
5. Piliin lamang ang mga permission na kailangan ng client.
6. Gumawa ng token at kopyahin ito agad. Hindi na maipapakita ng CPAlead ang kumpletong token muli pagkatapos mag-reload ang page.
7. I-store ito sa secret configuration ng pinagkakatiwalaang client at i-revoke ito kapag natapos ang gawain.

Maaaring magkaroon ang advertiser ng hanggang 10 aktibong Campaign API token. Gumamit ng hiwalay na token para sa magkakahiwalay na integration para malimitahan mo ang permissions, masuri ang paggamit, at ma-revoke ang isang integration nang hindi naaantala ang iba.

Saan gagawa ng iyong Campaign API token

Ang Campaign API token ay ang pribadong API credential na ipinapadala sa Authorization header. Hindi ito ang iyong CPAlead password, at hindi ito magagamit para mag-sign in sa CPAlead dashboard. Pagkatapos mag-sign in, buksan ang Setup → API, piliin ang Campaign API, at gamitin ang Create a token form.

Base URL, authentication, at response format

Ang mga authenticated request ay nagpapadala ng token nang isang beses sa HTTP authorization header. Huwag kailanman ilagay ito sa URL o query string.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Para sa mga curl example sa ibaba, mas ligtas na i-store ang authorization header sa isang local curl configuration file na hindi kasama sa source control at ikaw lamang ang makakabasa:

# cpalead-auth.cfg
header = "Authorization: Bearer YOUR_TOKEN"
header = "Accept: application/json"

# Restrict the file before using it:
chmod 600 cpalead-auth.cfg

Ang matagumpay na response ay may data object o listahan kasabay ng meta. Kasama sa metadata ang request_id at kasalukuyang schema version, at maaaring may pagination, resource version, o idempotent-replay flag. Ang error response ay may error object kasabay ng meta. I-save ang public request_id kapag nagte-troubleshoot kasama ang support, pero huwag kailanman ipadala sa support ang iyong bearer token.

Hakbang 1: Basahin ang live requirements

Ang requirements ang source of truth para sa kung ano ang puwedeng isumite ng account ngayon. Kabilang dito ang kasalukuyang schema at terms versions, eligibility sa account creation, sinusuportahang bansa at device, field limits, campaign-type rules, pricing ranges, schedules, launch packages, tracking requirements, image rules, at inirerekomendang workflow.

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/requirements?type=CPA"

Gamitin ang type=CPA, type=CPI, o type=CPC para limitahan ang response. Huwag i-hard-code ang schema version, terms version, payout limit, bid, budget, launch package, country, device, o minimum app version mula sa lumang halimbawa. Kunin muli ang requirements kapag iniulat ng server na luma na ang isang value o version.

Ang tatlong campaign type

• CPA: Nagbabayad para sa isang idineklarang aksyon. Dapat maglaman ang tracking URL ng {CLICK_ID}, at bahagi ng create shape ang preview URL, conversion goal, daily cap, at launch package.
• CPI: Nagbabayad para sa install o naka-configure na app event. Ginagamit nito ang {CLICK_ID} at nagdaragdag ng app-oriented na mga pagpipilian gaya ng device platform, tracking method, supported iOS version, at proxy handling.
• CPC: Nagbabayad para sa valid click. Gumagamit ito ng bid at daily budget sa halip na conversion payout, daily cap, at launch package.

Lahat ng money value ng Campaign API ay nasa USD, at ang API schedules ay gumagamit ng UTC. Basahin ang ibinalik na requirements at ipakita ang mga fact na iyon sa taong aapruba sa request.

Hakbang 2: Mag-upload ng campaign image

Ang create request ay hindi tumatanggap ng remote image URL. I-upload muna ang file bilang multipart form data, pagkatapos ilagay ang ibinalik na pansamantalang image ID sa image_upload_id.

curl --config cpalead-auth.cfg \
  --request POST \
  --form "[email protected]" \
  "https://www.cpalead.com/api/v1/advertiser/images"

• Tinanggap na sources: JPG, JPEG, PNG, GIF, BMP, at WebP.
• Pinakamataas na laki ng file: 2 MiB.
• Source width at height: bawat isa ay dapat nasa pagitan ng 200 at 4096 pixels.
• Naka-store na resulta: isang hindi animated, walang metadata na 200×200 WebP crop.
• Habang hindi pa nagagamit na lifetime ng upload: 24 oras.
• Limit ng outstanding upload: hanggang 25 kasalukuyang hindi pa nagagamit na image uploads.
• Gamitin: isang campaign create o image update. Mag-upload muli para sa ibang campaign.

Maaaring i-check ng validation kung ang isang image ID ay kabilang sa iyong account at puwedeng gamitin nang hindi ito nauubos. Kinokonsumo ito ng matagumpay na campaign write. Ang pag-replay ng parehong natapos na create gamit ang parehong idempotency key ay magbabalik ng naka-store na resulta; hindi ito lilikha ng pangalawang campaign mula sa nagamit nang image.

Hakbang 3: Bumuo ng kumpletong campaign JSON

Ang API ay gumagamit ng mahigpit na JSON objects. Ang mga hindi kilalang field ay tinatanggihan sa halip na tahimik na hindi pansinin. Mas ligtas nito ang isang AI integration: ang maling baybay o imbentong property ay nagiging nakikitang validation issue sa halip na aksidenteng campaign setting.

Ang sumusunod na halimbawa ng CPA ay isang template, hindi handa para sa pagsusumite. Palitan ang bawat COPY_FROM_REQUIREMENTS na value, image ID, URL, payout, bansa, cap, at public description ng mga nirepasong value para sa iyong totoong offer.

{
  "schema_version": "COPY_FROM_REQUIREMENTS",
  "external_id": "signup-campaign-us-001",
  "type": "CPA",
  "name": "US Account Signup",
  "creative": {
    "title": "Create Your Free Account",
    "description": "Register and confirm your email",
    "conversion_goal": "Create an account"
  },
  "tracking": {
    "url": "https://tracker.example.com/click?click_id={CLICK_ID}",
    "preview_url": "https://www.example.com/signup",
    "gaid_idfa_filler": false
  },
  "targeting": {
    "countries": ["US"],
    "device": "all_devices",
    "tools_only": false
  },
  "pricing": {
    "payout": "0.50",
    "daily_cap": 20,
    "currency": "USD"
  },
  "schedule": {
    "mode": "always",
    "start_time": "00:00",
    "end_time": "23:59",
    "timezone": "UTC"
  },
  "publisher_access": {
    "mode": "all",
    "publisher_ids": []
  },
  "launch_package": {
    "amount": "COPY_FROM_REQUIREMENTS"
  },
  "image_upload_id": "cimg_COPY_FROM_IMAGE_UPLOAD",
  "terms": {
    "version": "COPY_FROM_REQUIREMENTS",
    "accepted": true
  }
}

Mahalagang tracking rule para sa CPA at CPI

Dapat maglaman ang tracking URL ng eksaktong {CLICK_ID} macro. Dapat i-save ng iyong tracker o affiliate platform ang numeric value na inilalagay doon ng CPAlead at ibalik ang naka-save na click ID na iyon sa CPAlead advertiser postback pagkatapos ng conversion. Huwag ilagay ang postback URL ng CPAlead sa campaign tracking URL. Para sa buong paliwanag mula click hanggang postback, gamitin ang public advertiser postback guide.

Hakbang 4: I-validate bago lumikha

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/validate"

Ang validation ay nagbabalik ng HTTP 200 na may data.valid, isang errors list, at isang warnings list. Maaari pa ring maglaman ang 200 response ng valid: false, kaya dapat suriin ng client ang value na iyon sa halip na ituring na approval ang HTTP status lamang. Bawat issue ay gumagamit ng JSON Pointer path gaya ng /tracking/url, /pricing/payout, o /image_upload_id. Dapat ayusin ng isang AI agent ang tanging tinukoy na field, i-validate muli, at ipakita ang final JSON sa may-ari ng account bago humingi ng create permission.

Ang valid na response ay nangangahulugang pumasa ang payload sa kasalukuyang validation at persistence preflight. Hindi ito pangako ng approval, activation, traffic, conversions, o hinaharap na eligibility. Ang real-time review, funding, account access, holds, schedule, cap, at state checks ay patuloy na nalalapat sa writes at lifecycle actions.

Hakbang 5: Lumikha nang ligtas gamit ang idempotency

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-signup-campaign-us-001" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns"

Ang create, start, at pause ay nangangailangan ng Idempotency-Key na may 8 hanggang 200 nakikitang ASCII characters. Gumamit ng bagong key para sa bawat nilalayong aksyon. Kung pumalya ang koneksyon at hindi mo alam kung natapos ang aksyon, ulitin ang identical na aksyon gamit ang parehong key. Maaaring i-replay ng CPAlead ang natapos na response sa halip na lumikha o maningil nang dalawang beses.

• Parehong key at parehong intensyon: Maaaring i-replay ang natapos na response gamit ang meta.idempotent_replay=true.
• Parehong key pero may binagong detalye: Nagbabalik ang API ng idempotency conflict.
• Parehong external ID pero may binagong detalye: Nagbabalik din ng conflict ang API.
• Nakaprocess pa ang nakaraang request: Maghintay sa naiulat na pagitan, pagkatapos ay ulitin ang parehong intensyon gamit ang parehong key.

Ang opsyonal na external_id ay sarili mong stable reference para sa create operation. Makakatulong ito sa reconciliation, ngunit hindi ito maaaring muling gamitin para sa ibang campaign na nilalayon.

Tatlong campaign bago ang deposit

Ang advertiser account ay maaaring lumikha ng hanggang tatlong kabuuang self-serve CPA, CPI, o CPC campaign bago ang unang matagumpay na advertiser deposit. Binibilang pa rin ang paused, denied, at archived campaign dahil hindi dapat malusutan ng paggawa at pag-archive ng mga throwaway campaign ang limit. Pagkatapos ng matagumpay na deposit, hindi na nalalapat ang partikular na limit na ito sa paglikha; nalalapat pa rin ang karaniwang review, balance, payout, budget, at activation rules.

Basahin at i-filter ang mga campaign

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/campaigns?type=CPA&state=paused&page=1&per_page=25"

Sinusuportahan ng list endpoint ang campaign type, public state, updated_since timestamp, page, at per-page filters. Ang default ng pagination ay 25 campaign at pinapayagan ang hanggang 100 bawat page. Ang mga public state choice ay active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, at unavailable. Ang archived campaigns ay lumilitaw lamang kapag tahasan mong sinala ang state=archived.

Ang campaign resource ay naglalaman ng ID nito, opsyonal na external ID, version, type, name, creative, tracking, targeting, pricing, schedule, publisher-access setting, image URL, timestamps, at public state. Kasama rin sa state ang review, desired-delivery, delivery-reason, at capability hints. Advisory lamang ang capability hints: kunin ang pinakabagong campaign at hawakan ang totoong response ng operasyon dahil maaaring magbago ang account, funding, review, hold, at schedule conditions.

Mag-update gamit ang ETag version protection

Ang campaign edit ay gumagamit ng optimistic concurrency. Una, kunin ang campaign at i-save ang eksaktong nakapaloob sa panipi na ETag response header. Pagkatapos, ipadala ang value na iyon sa If-Match kasama ng PATCH request. Pinipigilan nito ang isang browser, agent, o integration na tahimik na ma-overwrite ang mas bagong pagbabagong ginawa sa ibang lugar.

# First retrieve the latest campaign and its ETag.
curl --config cpalead-auth.cfg \
  --dump-header campaign-headers.txt \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

# Then send a reviewed partial update with that exact quoted ETag.
curl --config cpalead-auth.cfg \
  --request PATCH \
  --header "Content-Type: application/json" \
  --header 'If-Match: "COPY_THE_LATEST_ETAG"' \
  --data-binary '{"creative":{"description":"Updated public description"}}' \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

• Walang If-Match: Nagbabalik ang API ng HTTP 428.
• Luma na ang If-Match: Nagbabalik ang API ng HTTP 412 na may kasalukuyang version metadata.
• Pagkatapos ng 412: Kunin muli ang campaign, ihambing ang mga pagbabago, humingi ng approval, at subukang muli gamit ang bagong ETag.
• Pagkatapos ng malabong resulta ng network: Kunin ang campaign bago magpadala ng isa pang update.

Tinatanggap lang ng PATCH ang public campaign fields. Isinasama nito ang ibinigay na partial object sa kasalukuyang campaign at ini-validate ang kumpletong resulta. Ang ilang edit ay maaaring mangailangan ng isa pang review o makapagpabago ng delivery, kaya basahin ang response state sa tuwing gagawa.

Ang start at pause ay tahasan, walang-body na actions

# Start an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: start-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/start"

# Pause an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: pause-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/pause"

Huwag magpadala ng JSON body—kahit {}—sa start o pause. Bago magsimula, kumpirmahin ang campaign, balance, payout o bid, epekto ng launch-package, bansa, device, schedule, cap o budget, landing page, at tracking. Pagkatapos ng response, suriin ang public state; maaaring naka-enable ang campaign ngunit nasa labas ng pang-araw-araw na schedule nito, naka-pause para sa funding, nasa cap nito, o hindi pa rin makapag-deliver.

Mga HTTP status at error na dapat maunawaan ng integration

Mag-automate batay sa HTTP status at stable error.code, hindi lang sa pagkakasulat ng mensahe. Kasama sa validation details ang path, code, at plain-English message. Isama ang response request_id kapag nakikipag-ugnayan sa support.

Rate limits at responsableng retries

Ang Campaign API requests at authentication ay may rate limit para protektahan ang advertisers at ang service. Maaaring magbago ang limits, kaya gamitin ang live OpenAPI schema at response headers sa halip na mag-hard-code ng bilang ng request. Kapag nagbalik ang API ng HTTP 429, maghintay sa Retry-After imbes na agad ulitin ang requests. Gumamit ng pagination, updated_since, at lokal na caching ng hindi nagbago na public requirements para maiwasan ang hindi kailangang mga tawag.

Isang prompt na puwede mong ibigay sa pinagkakatiwalaang AI agent

Ibahagi muna ang guide at OpenAPI URL. I-configure ang token sa private secret settings ng agent platform; huwag maglagay ng totoong token sa prompt na ito.

Read this CPAlead Campaign API guide and the public OpenAPI schema.

Do not ask me to paste a bearer token into chat. Use only the token configured
privately in the integration. Begin with read and validate operations.

1. Ask whether I am creating CPA, CPI, or CPC.
2. Call the matching requirements endpoint.
3. Ask me for every missing business value and explain any financial,
   tracking, targeting, schedule, review, or delivery effect.
4. Draft strict campaign JSON and validate it.
5. Repair validation errors by their JSON Pointer paths.
6. Show me the final normalized intent and ask for confirmation before
   uploading, creating, updating, starting, or pausing anything.
7. Use a unique idempotency key for create, start, and pause.
8. Retrieve the latest campaign and ETag before an update.
9. After every write, report the campaign ID, public state, request ID,
   warnings, and recommended next step.
10. Never attempt archive or delete because those operations are not in
    the Campaign API.

Security checklist para sa AI, MCP, plugins, at code

• Least privilege: Magsimula sa read at validate. Magdagdag lamang ng isang write permission kapag kailangan.
• Maikling expiry: Mas mainam ang 48-hour option para sa isang beses na AI setup task.
• Hiniwalay na tokens: Bigyan ang bawat agent o integration ng sarili nitong may pangalang token.
• Pribadong storage: Panatilihin ang tokens sa secret settings, hindi sa URLs, prompts, logs, analytics, screenshots, o repositories.
• Pagkumpirma ng tao: Humiling ng buod bago mag-create, update, start, o pause.
• Ligtas na retries: Panatilihin ang parehong key at payload pagkatapos ng hindi tiyak na idempotent result.
• Version checks: Huwag kailanman mag-update nang hindi kinukuha ang pinakabagong ETag.
• Response checks: Basahin ang public state at request ID pagkatapos ng bawat write.
• Mag-revoke agad: Alisin ang access mula sa Advertising API page kapag tapos na ang trabaho o maaaring nag-leak ang token.

Mga madalas itanong

Saan ko makikita ang aking CPAlead API key?

Para sa Campaign API, ang credential ay tinatawag na Campaign API token. Mag-sign in at buksan ang Advertising → Setup → API, pagkatapos gamitin ang Create a token. Kopyahin agad ang token dahil isang beses lamang ipinapakita ng CPAlead ang buong value.

Kayang lumikha ng API ng CPA, CPI, at CPC campaigns?

Oo. Bawat type ay may mahigpit ngunit magkaibang JSON shape. Kunin ang requirements para sa type na iyon bago ito buuin.

Maaari ba akong mag-validate nang hindi pinapayagang lumikha ang AI ng kahit ano?

Oo. Bigyan ang token ng campaigns:validate lamang, at opsyonal ang campaigns:read. Hindi kailangan ng create permission para sa requirements at validation.

Ang valid na response ba ay nangangahulugang aprubado ang campaign?

Hindi. Nangangahulugan ito na pumasa ang kasalukuyang payload sa validation at preflight. Nalalapat pa rin ang review, funding, account access, holds, caps, schedules, at real-time state.

Puwede bang agad magsimula ang create ng campaign?

Maaaring oo, depende sa account at campaign. Maaari rin itong pumasok sa review. Palaging suriin ang ibinalik na public state. Maaari ring maningil ang CPA o CPI activation ng hindi pa nababayarang napiling launch package.

Maaari ba akong mag-upload ng image mula sa remote URL?

Hindi. I-upload ang image file sa pamamagitan ng POST /images. Nagbabalik ang CPAlead ng pansamantala, single-use na image ID.

Maaari ba akong lumikha ng maraming offers nang sabay-sabay?

Walang bulk-create operation. I-validate at lumikha ng isang campaign bawat request, gumamit ng natatanging external ID at idempotency key, at sundin ang rate limits at mga patakaran sa account creation.

Maaari bang mag-archive o mag-delete ang API ng campaign?

Hindi. Ang kasalukuyang public API ay maaaring magsimula at mag-pause ng karapat-dapat na campaigns ngunit hindi nagbibigay ng archive o delete. Gamitin ang advertiser dashboard para sa archival.

Bakit tumanggap ng HTTP 412 ang aking update?

Nagbago ang campaign pagkatapos mo itong kunin. Kunin ito muli, suriin ang pinakabagong data, i-merge ang nilalayon mong pagbabago, at subukang muli gamit ang bagong ETag.

Bakit nagbalik ng HTTP 409 ang create?

Basahin ang stable error code. Kabilang sa posibleng public reasons ang muling ginamit na idempotency key o external ID na may ibang data, isang naunang request na nakaprocess pa, ang tatlong-campaign na pre-deposit limit, mga restriksiyon sa funding o account, isang hold, o isang state conflict.

Dapat bang kopyahin ng application ko ang field limits mula sa artikulong ito?

Hindi. Ipinaliliwanag ng artikulong ito ang workflow. Dapat basahin ng iyong application ang live requirements at OpenAPI schema upang manatiling awtoritatibo ang kasalukuyang values.

Machine-friendly na Campaign API fact sheet

Magsimula sa read at validate

Dinisenyo ang Campaign API upang ang advertiser ay makapagsimula nang may pag-iingat. Bigyan ang isang pinagkakatiwalaang agent ng public guide at schema, bigyan ng read at validation access, at hayaan itong maghanda ng request nang hindi binabago ang account. Kapag tama na ang JSON at nauunawaan ng may-ari ang posibleng review, delivery, at financial effects, idagdag lamang ang write permission na kailangan para sa susunod na kumpirmadong aksyon.

Buksan ang Campaign API sa Advertiser API Center upang lumikha ng token, o buksan ang public Campaign API OpenAPI schema upang suriin ang kasalukuyang contract. Ang Publisher API documentation ay hiwalay at tumatalakay sa pagkuha ng offers at reporting ng publishers. Kung hindi malinaw ang isang response, panatilihing pribado ang token at makipag-ugnayan sa Advertiser Support gamit ang public request ID at campaign ID.

Napansin mo ba ang isang pagkakamali o isang aspeto ng post na ito na nangangailangan ng pagwawasto? Mangyaring ibigay ang link ng post at makipag-ugnayan sa amin. Pinahahalagahan namin ang iyong feedback at agarang aayusin ang isyu.