API sa Kampanya sa Advertiser sa CPAlead: Paghimo ug Pagdumala sa mga Alok

Ang CPAlead Campaign API nagtugot sa usa ka verified self-serve advertiser nga mogamit og code, AI agent, MCP server, o plugin aron magtrabaho sa CPA, CPI, ug CPC campaigns. Ang usa ka authorized client makabasa sa kasamtangang campaign requirements, makavalidate sa kompleto nga campaign sa dili pa kini i-save, makapasa og creative, makabuhat og campaign, makalista ug makakuha og campaigns, makausab og campaign nga adunay version protection, ug klarong makasugod o makapause sa usa ka eligible campaign.

Kini ang automation companion sa normal advertiser dashboard. Kung gusto una nimo og field-by-field nga pagpasabot sa mga campaign type, tracking, targeting, payouts, caps, funding, review, ug launch, basaha ang How to Advertise on CPAlead in 2026: Add and Launch Your First Offer. Gamita kini nga artikulo kung andam na ka nga i-express kana nga setup isip structured JSON ug controlled API actions.

Unsa ang mahimo sa Campaign API

Ang API dili karon naghatag og archive, delete, bulk-create, o generic toggle operation. Ang archive o delete nga trabaho workflow sa dashboard. Ang start ug pause bulag nga actions aron ang usa ka tawo o AI client makapangayo og klarong kumpirmasyon sa dili pa usbon ang delivery.

Lahi ang Campaign API ug Offer API Import

• Campaign API: Usa ka scoped bearer-token API nga nag-validate, naghimo, nagbasa, nag-edit, nagsugod, ug nag-pause og campaigns sa imong advertiser account.
• Offer API Import: Usa ka bulag nga advertiser-dashboard workflow nga mobasa og offers gikan sa compatible external feed ug mag-map sa mga field niini ngadto sa CPAlead.

Ang Advertiser API Center nagbulag niining mga tool sa lain-laing pahina. Mag-sign in, ablihi ang Setup → API, unya pilia ang tool nga angay sa imong buluhaton. Gamita ang Campaign API kung ang imong kaugalingong application, agent, MCP server, o plugin adunay na sa offer data ug nanginahanglan og structured nga paagi sa pagtrabaho uban sa CPAlead. Gamita ang importer kung ang CPAlead ang magkuha ug mag-map sa usa ka supported offer feed. Ayaw paghatag og mas lapad nga token kaysa sa gikinahanglan sa iyang trabaho.

Paghimo og Campaign API token

1. Mag-sign in sa usa ka verified self-serve advertiser account.
2. Ablihi ang Setup → API, unya pilia ang Campaign API.
3. Hatagi og makaila nga ngalan ang token, sama sa “Campaign validator” o “My MCP agent.”
4. Pilia ang expiration. Ang 48-hour nga opsyon girekomendar para sa AI setup; anaa usab ang 30-day, 90-day, ug 365-day nga mga opsyon.
5. Pilia lamang ang mga permission nga gikinahanglan sa client.
6. Himua ang token ug kopyaha kini dayon. Dili na mapakita sa CPAlead ang kompleto nga token pag-usab human ma-refresh ang page.
7. I-store kini sa secret configuration sa masaligan nga client ug i-revoke kini kung mahuman na ang buluhaton.

Ang usa ka advertiser mahimong adunay hangtod 10 ka aktibo nga Campaign API tokens. Gamita ang bulag nga mga token para sa bulag nga integrations aron makapugong ka sa permissions, makareview og paggamit, ug makarevoke og usa ka integration nga dili maapektuhan ang lain.

Asa paghimoon ang imong Campaign API token

Ang Campaign API token mao ang pribadong API credential nga gipadala sa Authorization header. Dili kini imong CPAlead password, ug dili kini magamit sa pag-sign in sa CPAlead dashboard. Human sa pag-sign in, ablihi ang Setup → API, pilia ang Campaign API, ug gamita ang Create a token form.

Base URL, authentication, ug response format

Ang authenticated requests magpadala sa token kausa sa HTTP authorization header. Ayaw gayod ibutang kini sa URL o query string.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Para sa mga curl example sa ubos, mas luwas nga setup ang pagtipig sa authorization header sa usa ka local curl configuration file nga wala giapil sa source control ug mabasa lamang nimo:

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

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

Ang malampusong response adunay data object o list plus meta. Ang metadata naglakip sa request_id ug current schema version, ug mahimo usab maglakip sa pagination, usa ka resource version, o usa ka idempotent-replay flag. Ang error response adunay error object plus meta. I-save ang public request_id kung nag-troubleshoot ka uban sa support, pero ayaw gayod ipadala sa support ang imong bearer token.

Lakang 1: Basaha ang live requirements

Ang requirements mao ang source of truth para sa kung unsay mahimo karon i-submit sa account. Naglakip kini sa current schema ug terms versions, account creation eligibility, supported countries ug devices, field limits, campaign-type rules, pricing ranges, schedules, launch packages, tracking requirements, image rules, ug recommended workflow.

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

Gamita ang type=CPA, type=CPI, o type=CPC aron limitahan ang response. Ayaw i-hard-code ang schema version, terms version, payout limit, bid, budget, launch package, country, device, o minimum app version gikan sa karaang example. Kuhaa pag-usab ang requirements kung magreport ang server nga ang usa ka value o version daan na.

Ang tulo ka campaign type

• CPA: Mobayad para sa gideklarang aksyon. Ang tracking URL kinahanglan adunay {CLICK_ID}, ug ang preview URL, conversion goal, daily cap, ug launch package kabahin sa create shape.
• CPI: Mobayad para sa install o gi-configure nga app event. Gigamit niini ang {CLICK_ID} ug nagdugang og app-oriented nga mga pilian sama sa device platform, tracking method, supported iOS version, ug proxy handling.
• CPC: Mobayad para sa valid click. Gigamit niini ang bid ug daily budget imbes nga conversion payout, daily cap, ug launch package.

Tanang Campaign API money values naa sa USD, ug ang API schedules mogamit og UTC. Basaha ang gibalik nga requirements ug ipakita kining mga kamatuoran sa tawo nga nag-apruba sa request.

Lakang 2: I-upload ang campaign image

Ang create requests dili modawat og remote image URL. I-upload una ang file isip multipart form data, unya ibutang ang gibalik nga temporary image ID sa image_upload_id.

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

• Gidawat nga source: JPG, JPEG, PNG, GIF, BMP, ug WebP.
• Maximum file size: 2 MiB.
• Source width ug height: ang matag usa kinahanglan tali sa 200 ug 4096 pixels.
• Stored result: usa ka non-animated, metadata-free 200×200 WebP crop.
• Unused upload lifetime: 24 hours.
• Outstanding-upload limit: hangtod 25 ka karon unused image uploads.
• Gamita: usa ka campaign create o image update. Pag-upload pag-usab para sa lahi nga campaign.

Makavalidate aron masusi nga ang image ID kabahin sa imong account ug magamit pa nga dili kini ma-consume. Ang malampusong campaign write maoy mo-consume niini. Kung i-replay ang parehas nga nahuman nga create gamit ang parehas nga idempotency key, ibalik ang gitipig nga resulta; dili kini maghimo og ikaduhang campaign gikan sa na-consume nga image.

Lakang 3: Paghimo og kompleto nga campaign JSON

Ang API naggamit og higpit nga JSON objects. Ang wala mailhi nga mga field i-reject imbes nga hilom nga ilabay. Mas luwas kana para sa AI integration: ang sayop nga spelling o imbentong property mahimong makita nga validation issue imbes nga aksidenteng campaign setting.

Ang mosunod nga CPA example usa ka template, dili andam nga i-submit nga campaign. Ilisi ang matag COPY_FROM_REQUIREMENTS nga value, image ID, URL, payout, country, cap, ug public description sa gi-review nga mga value para sa imong tinuod nga 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
  }
}

Importanteng CPA ug CPI tracking rule

Ang tracking URL kinahanglan adunay eksaktong {CLICK_ID} macro. Ang imong tracker o affiliate platform kinahanglan mag-save sa numeric value nga ibutang sa CPAlead didto ug ibalik kana nga save nga click ID ngadto sa CPAlead advertiser postback human sa conversion. Ayaw ibutang ang postback URL sa CPAlead sa campaign tracking URL. Para sa tibuok click-to-postback nga pagpasabot, gamita ang public advertiser postback guide.

Lakang 4: I-validate sa dili pa maghimo

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 mobalik og HTTP 200 uban sa data.valid, usa ka errors list, ug usa ka warnings list. Ang 200 response mahimo gihapon adunay valid: false, busa ang client kinahanglan mosusi sa maong value imbes nga ang HTTP status ra ang tan-awon isip aprobasyon. Matag issue mogamit og JSON Pointer path sama sa /tracking/url, /pricing/payout, o /image_upload_id. Ang usa ka AI agent kinahanglan mag-ayo lamang sa gipasabot nga field, mag-validate pag-usab, ug ipakita ang final JSON sa tag-iya sa account sa dili pa mangayo og create permission.

Ang valid nga response nagpasabot nga ang payload mopasar sa kasamtangang validation ug persistence preflight. Dili kini saad sa approval, activation, traffic, conversions, o umaabot nga eligibility. Ang real-time review, funding, account access, holds, schedule, cap, ug state checks mag-aplikar gihapon sa writes ug lifecycle actions.

Lakang 5: Maghimo nga luwas 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, ug pause nanginahanglan og Idempotency-Key nga adunay 8 hangtod 200 ka makita nga ASCII characters. Gamita ang bag-ong key para sa matag tuyo nga action. Kung mapakyas ang koneksyon ug wala ka kabalo kung nahuman ba ang action, i-retry ang parehas nga action gamit ang parehas nga key. Makareplay ang CPAlead sa nahuman nga response imbes nga maghimo o maningil og kaduha.

• Parehas nga key ug parehas nga intent: Ang nahuman nga response mahimong i-replay uban sa meta.idempotent_replay=true.
• Parehas nga key nga nausab ang detalye: Ang API mobalik og idempotency conflict.
• Parehas nga external ID nga nausab ang detalye: Ang API mobalik usab og conflict.
• Ang una nga request nagproseso pa: Hulat sa gi-report nga interval, unya i-retry ang parehas nga intent gamit ang parehas nga key.

Ang opsyonal nga external_id mao ang imong kaugalingong stable reference para sa create operation. Makatabang kini sa reconciliation, pero dili kini angay magamit pag-usab para sa lahi nga tuyo nga campaign.

Tulo ka campaigns sa wala pa ang deposit

Ang usa ka advertiser account mahimong maghimo hangtod tulo ka total self-serve CPA, CPI, o CPC campaigns sa wala pa ang iyang unang malampusong advertiser deposit. Ang paused, denied, ug archived campaigns apil gihapon sa ihap kay ang paghimo ug pag-archive sa throwaway campaigns dili angay makalusot sa limit. Human sa malampusong deposit, kining partikular nga creation limit dili na mag-aplikar; ang normal review, balance, payout, budget, ug activation rules mag-aplikar gihapon.

Basaha ug i-filter ang campaigns

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

Ang list endpoint nagsuporta sa campaign type, public state, usa ka updated_since timestamp, page, ug per-page filters. Ang pagination default kay 25 campaigns ug nagtugot hangtod 100 per page. Ang public state choices mao ang active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, ug unavailable. Ang archived campaigns makita lamang kung klaro nimo nga i-filter ang state=archived.

Ang usa ka campaign resource naglakip sa iyang ID, opsyonal nga external ID, version, type, name, creative, tracking, targeting, pricing, schedule, publisher-access setting, image URL, timestamps, ug public state. Ang state naglakip usab og review, desired-delivery, delivery-reason, ug capability hints. Ang capability hints advisory ra: kuhaa ang pinakabag-ong campaign ug dumala ang tinuod nga operation response kay ang account, funding, review, hold, ug schedule conditions mahimong mausab.

I-update gamit ang ETag version protection

Ang campaign edits mogamit og optimistic concurrency. Una kuhaa ang campaign ug i-save ang eksaktong quoted ETag response header. Dayon ipadala kana nga value sa If-Match uban sa PATCH request. Kini mopahunong sa usa ka browser, agent, o integration nga hilom nga mag-overwrite sa mas bag-ong change nga gihimo sa laing dapit.

# 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"

• Walay If-Match: Ang API mobalik og HTTP 428.
• Stale If-Match: Ang API mobalik og HTTP 412 uban sa current version metadata.
• Human sa 412: Kuhaa pag-usab ang campaign, ikumpara ang mga kausaban, pangayo og approval, ug i-retry gamit ang bag-ong ETag.
• Human sa dili klarong network result: Kuhaa ang campaign sa dili pa magpadala og laing update.

Ang PATCH modawat lamang sa public campaign fields. Gihiusa niini ang gihatag nga partial object uban sa kasamtangang campaign ug gi-validate ang kompleto nga resulta. Ang uban nga edits mahimong manginahanglan og laing review o mag-usab sa delivery, busa basaha ang response state matag higayon.

Ang start ug pause klaro, walay body nga mga action

# 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"

Ayaw pagpadala og JSON body—bisan {}—sa start o pause. Sa dili pa magsugod, kumpirmahi ang campaign, balance, payout o bid, launch-package effect, countries, devices, schedule, cap o budget, landing page, ug tracking. Human sa response, susiha ang public state; ang campaign mahimong enabled pero gawas sa iyang daily schedule, paused for funding, naa sa cap, o sa laing paagi dili makadeliver.

HTTP statuses ug errors nga angay masabtan sa integration

Mag-automate base sa HTTP status ug stable error.code, dili sa mismong paghulagway sa message. Ang validation details naglakip og path, code, ug plain-English nga message. Apil ang response request_id kung mokontak sa support.

Rate limits ug responsable nga retries

Ang Campaign API requests ug authentication gi-rate limit aron protektahan ang advertisers ug ang service. Ang limits mahimong mausab, busa gamita ang live OpenAPI schema ug response headers imbes nga mag-hard-code og request count. Kung ang API mobalik og HTTP 429, hulata ang Retry-After imbes nga dayon balikon ang requests. Gamita ang pagination, updated_since, ug local caching sa wala mausab nga public requirements aron malikayan ang wala kinahanglana nga calls.

Usa ka prompt nga mahimo nimong ihatag sa masaligan nga AI agent

Ipaambit una ang guide ug OpenAPI URL. I-configure ang token sa pribadong secret settings sa agent platform; ayaw pagsulod og tinuod nga token niini nga prompt.

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, ug code

• Least privilege: Sugdi sa read ug validate. Idugang ang usa lang ka write permission kung kinahanglan na.
• Mubo nga expiry: Pilia ang 48-hour nga opsyon para sa one-time AI setup task.
• Bulag nga tokens: Hatagi ang matag agent o integration og kaugalingong ginganlan nga token.
• Pribadong storage: Ibutang ang tokens sa secret settings, dili sa URLs, prompts, logs, analytics, screenshots, o repositories.
• Kumpirmasyon sa tawo: Kinahanglan og summary sa dili pa create, update, start, o pause.
• Luwas nga retries: Ipreserba ang parehas nga key ug payload human sa dili sigurado nga idempotent result.
• Version checks: Ayaw pag-update kung wala makuha ang pinakabag-ong ETag.
• Response checks: Basaha ang public state ug request ID human sa matag write.
• I-revoke dayon: Kuhaa ang access gikan sa Advertising API page kung nahuman na ang trabaho o posibleng na-leak ang token.

Frequently asked questions

Asa ko makakita sa akong CPAlead API key?

Para sa Campaign API, ang credential gitawag og Campaign API token. Mag-sign in ug ablihi ang Advertising → Setup → API, unya gamita ang Create a token. Kopyaha dayon ang token kay ang CPAlead mopakita sa kompleto nga value usa ra ka higayon.

Makahimo ba ang API og CPA, CPI, ug CPC campaigns?

Oo. Matag type adunay higpit pero lahi nga JSON shape. Kuhaa una ang requirements para nianang type sa dili pa kini buhaton.

Makavalidate ba ko nga dili tugotan ang AI nga moghimo og bisan unsa?

Oo. Hatagi ang token og campaigns:validate lamang, ug opsyonal campaigns:read. Ang requirements ug validation dili manginahanglan og create permission.

Ang valid response ba nagpasabot nga approved na ang campaign?

Dili. Nagpasabot kini nga ang kasamtangang payload mopasar sa validation ug preflight. Ang review, funding, account access, holds, caps, schedules, ug real-time state mag-aplikar gihapon.

Ang create ba makasugod dayon og campaign?

Mahimo, depende sa account ug campaign. Mahimo usab kini mapasa sa review. Kanunay susiha ang gibalik nga public state. Ang CPA o CPI activation mahimo usab mangolekta og wala pa mabayri nga napiling launch package.

Makahimo ba ko og image gikan sa remote URL?

Dili. I-upload ang image file pinaagi sa POST /images. Ang CPAlead mobalik og temporary single-use image ID.

Makahimo ba ko og daghang offers sa usa ka higayon?

Walay bulk-create operation. I-validate ug paghimo og usa ka campaign kada request, gamita ang lahi nga external ID ug idempotency key, ug tahora ang rate limits ug account creation rules.

Maka-archive o delete ba ang API og campaign?

Dili. Ang kasamtangang public API makasugod ug makapause sa eligible campaigns pero dili nag-expose og archive o delete. Gamita ang advertiser dashboard para sa archival.

Ngano HTTP 412 man ang akong update?

Nausab ang campaign human nimo kini makuha. Kuhaa pag-usab, i-review ang pinakabag-ong data, i-merge ang imong tuyo nga kausaban, ug i-retry gamit ang bag-ong ETag.

Ngano HTTP 409 man ang create?

Basaha ang stable error code. Ang posibleng public nga mga rason naglakip sa nagamit pag-usab nga idempotency key o external ID nga adunay lahi nga data, usa ka mas sayong request nga nagproseso pa, ang tulo-ka-campaign pre-deposit limit, funding o account restrictions, usa ka hold, o state conflict.

Ang akong application ba angay kopyahon ang field limits gikan niini nga artikulo?

Dili. Kini nga artikulo nagpasabot sa workflow. Ang imong application kinahanglan mobasa sa live requirements ug OpenAPI schema aron ang kasamtangang values magpabiling authoritative.

Machine-friendly Campaign API fact sheet

Sugdi sa read ug validate

Ang Campaign API gidisenyo aron ang advertiser makasugod nga mabinantayon. Ihatag sa masaligan nga agent ang public guide ug schema, hatagi og read ug validation access, ug pasagdi kini mag-andam og request nga dili mausab ang account. Kung sakto na ang JSON ug masabtan sa tag-iya ang posibleng review, delivery, ug financial effects, idugang lamang ang write permission nga gikinahanglan para sa sunod nga gikumpirmang aksyon.

Ablihi ang Campaign API sa Advertiser API Center aron maghimo og token, o ablihi ang public Campaign API OpenAPI schema aron susihon ang kasamtangang contract. Ang Publisher API documentation lahi ug naglangkob sa publishers nga nagkuha og offers ug pag-report. Kung dili klaro ang response, ipabiling pribado ang token ug kontaka ang Advertiser Support uban ang public request ID ug campaign ID.

Nakamatikod ka ba ug sayop o usa ka aspeto sa kining post nga nanginahanglan pagtul-id? Palihug ihatag ang link sa post ug pakigsulti kanamo. Gina-apresyar namo ang inyong mga feedback ug atimanon namo ang mga isyu sa madali.