CPAlead Advertiser Campaign API: Create and Manage Offers

The CPAlead Campaign API lets a verified self-serve advertiser use code, an AI agent, an MCP server, or a plugin to work with CPA, CPI, and CPC campaigns. An authorized client can read current campaign requirements, validate a complete campaign before saving it, upload a creative, create a campaign, list and retrieve campaigns, edit a campaign with version protection, and explicitly start or pause an eligible campaign.

This is the automation companion to the normal advertiser dashboard. If you first want a field-by-field explanation of campaign types, tracking, targeting, payouts, caps, funding, review, and launch, read How to Advertise on CPAlead in 2026: Add and Launch Your First Offer. Use this article when you are ready to express that setup as structured JSON and controlled API actions.

What the Campaign API can do

The API does not currently provide an archive, delete, bulk-create, or generic toggle operation. Archive or delete work remains a dashboard workflow. Start and pause are separate actions so a person or AI client can ask for clear confirmation before changing delivery.

Campaign API and Offer API Import are different

• Campaign API: A scoped bearer-token API that validates, creates, reads, edits, starts, and pauses campaigns in your advertiser account.
• Offer API Import: A separate advertiser-dashboard workflow that reads offers from a compatible external feed and maps its fields into CPAlead.

The Advertiser API Center keeps these tools on separate pages. Sign in, open Setup → API, then choose the tool that matches your task. Use the Campaign API when your own application, agent, MCP server, or plugin already has the offer data and needs a structured way to work with CPAlead. Use the importer when CPAlead should fetch and map a supported offer feed. Do not give an integration a broader token than its job requires.

Create a Campaign API token

1. Sign in to a verified self-serve advertiser account.
2. Open Setup → API, then select Campaign API.
3. Give the token a recognizable name, such as “Campaign validator” or “My MCP agent.”
4. Choose an expiration. The 48-hour option is recommended for AI setup; 30-day, 90-day, and 365-day options are also available.
5. Select only the permissions the client needs.
6. Create the token and copy it immediately. CPAlead cannot display the complete token again after the page reloads.
7. Store it in the trusted client’s secret configuration and revoke it when the task ends.

An advertiser may have up to 10 active Campaign API tokens. Use separate tokens for separate integrations so you can limit permissions, review use, and revoke one integration without interrupting another.

Where to create your Campaign API token

A Campaign API token is the private API credential sent in the Authorization header. It is not your CPAlead password, and it cannot be used to sign in to the CPAlead dashboard. After signing in, open Setup → API, select Campaign API, and use the Create a token form.

Base URL, authentication, and response format

Authenticated requests send the token once in the HTTP authorization header. Never put it in the URL or query string.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

For the curl examples below, a safer setup is to store the authorization header in a local curl configuration file that is excluded from source control and readable only by you:

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

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

A successful response has a data object or list plus meta. Metadata includes a request_id and current schema version, and may include pagination, a resource version, or an idempotent-replay flag. An error response has an error object plus meta. Save the public request_id when troubleshooting with support, but never send support your bearer token.

Step 1: Read live requirements

Requirements are the source of truth for what the account can submit now. They include the current schema and terms versions, account creation eligibility, supported countries and devices, field limits, campaign-type rules, pricing ranges, schedules, launch packages, tracking requirements, image rules, and recommended workflow.

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

Use type=CPA, type=CPI, or type=CPC to limit the response. Do not hard-code a schema version, terms version, payout limit, bid, budget, launch package, country, device, or minimum app version from an old example. Fetch requirements again when the server reports that a value or version is out of date.

The three campaign types

• CPA: Pays for a declared action. The tracking URL must contain {CLICK_ID}, and a preview URL, conversion goal, daily cap, and launch package are part of the create shape.
• CPI: Pays for an install or configured app event. It uses {CLICK_ID} and adds app-oriented choices such as device platform, tracking method, supported iOS version, and proxy handling.
• CPC: Pays for a valid click. It uses a bid and daily budget instead of a conversion payout, daily cap, and launch package.

All Campaign API money values are in USD, and API schedules use UTC. Read the returned requirements and display those facts to the person approving the request.

Step 2: Upload a campaign image

Create requests do not accept a remote image URL. Upload the file first as multipart form data, then place the returned temporary image ID in image_upload_id.

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

• Accepted sources: JPG, JPEG, PNG, GIF, BMP, and WebP.
• Maximum file size: 2 MiB.
• Source width and height: each must be between 200 and 4096 pixels.
• Stored result: a non-animated, metadata-free 200×200 WebP crop.
• Unused upload lifetime: 24 hours.
• Outstanding-upload limit: up to 25 current unused image uploads.
• Use: one campaign create or image update. Upload again for a different campaign.

Validation can check that an image ID belongs to your account and remains usable without consuming it. The successful campaign write consumes it. Replaying the same completed create with the same idempotency key returns the stored result; it does not create a second campaign from the consumed image.

Step 3: Build complete campaign JSON

The API uses strict JSON objects. Unknown fields are rejected instead of silently ignored. That makes an AI integration safer: a misspelled or invented property becomes a visible validation issue rather than an accidental campaign setting.

The following CPA example is a template, not a ready-to-submit campaign. Replace every COPY_FROM_REQUIREMENTS value, image ID, URL, payout, country, cap, and public description with reviewed values for your real 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
  }
}

Important CPA and CPI tracking rule

The tracking URL must contain the exact {CLICK_ID} macro. Your tracker or affiliate platform must save the numeric value CPAlead inserts there and return that saved click ID to the CPAlead advertiser postback after the conversion. Do not place CPAlead’s postback URL in the campaign tracking URL. For the full click-to-postback explanation, use the public advertiser postback guide.

Step 4: Validate before creating

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"

Validation returns HTTP 200 with data.valid, an errors list, and a warnings list. A 200 response can still contain valid: false, so a client must inspect that value instead of treating the HTTP status alone as approval. Each issue uses a JSON Pointer path such as /tracking/url, /pricing/payout, or /image_upload_id. An AI agent should repair only the indicated field, validate again, and show the final JSON to the account owner before requesting create permission.

A valid response means the payload passes the current validation and persistence preflight. It is not a promise of approval, activation, traffic, conversions, or future eligibility. Real-time review, funding, account access, holds, schedule, cap, and state checks still apply to writes and lifecycle actions.

Step 5: Create safely with 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"

Create, start, and pause require an Idempotency-Key containing 8 to 200 visible ASCII characters. Use a new key for each intended action. If the connection fails and you do not know whether the action completed, retry the identical action with the same key. CPAlead can replay the completed response instead of creating or charging twice.

• Same key and same intent: The completed response can be replayed with meta.idempotent_replay=true.
• Same key with changed details: The API returns an idempotency conflict.
• Same external ID with changed details: The API also returns a conflict.
• Previous request still processing: Wait the reported interval, then retry the same intent with the same key.

The optional external_id is your own stable reference for the create operation. It can make reconciliation easier, but it must not be reused for a different intended campaign.

Three campaigns before a deposit

An advertiser account may create up to three total self-serve CPA, CPI, or CPC campaigns before its first successful advertiser deposit. Paused, denied, and archived campaigns still count because creating and archiving throwaway campaigns must not bypass the limit. After a successful deposit, this specific creation limit no longer applies; normal review, balance, payout, budget, and activation rules still do.

Read and filter campaigns

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

The list endpoint supports campaign type, public state, an updated_since timestamp, page, and per-page filters. Pagination defaults to 25 campaigns and allows up to 100 per page. Public state choices are active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived, and unavailable. Archived campaigns appear only when you explicitly filter for state=archived.

A campaign resource includes its ID, optional external ID, version, type, name, creative, tracking, targeting, pricing, schedule, publisher-access setting, image URL, timestamps, and public state. The state also includes review, desired-delivery, delivery-reason, and capability hints. Capability hints are advisory: retrieve the latest campaign and handle the real operation response because account, funding, review, hold, and schedule conditions can change.

Update with ETag version protection

Campaign edits use optimistic concurrency. First retrieve the campaign and save the exact quoted ETag response header. Then send that value in If-Match with the PATCH request. This stops one browser, agent, or integration from silently overwriting a newer change made somewhere else.

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

• No If-Match: The API returns HTTP 428.
• Stale If-Match: The API returns HTTP 412 with the current version metadata.
• After a 412: Retrieve the campaign again, compare the changes, ask for approval, and retry with the new ETag.
• After an unclear network result: Retrieve the campaign before sending another update.

PATCH accepts public campaign fields only. It merges the supplied partial object with the current campaign and validates the complete result. Some edits may require another review or change delivery, so read the response state every time.

Start and pause are explicit, bodyless 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"

Do not send a JSON body—not even {}—to start or pause. Before starting, confirm the campaign, balance, payout or bid, launch-package effect, countries, devices, schedule, cap or budget, landing page, and tracking. After the response, inspect the public state; a campaign can be enabled but outside its daily schedule, paused for funding, at its cap, or otherwise unable to deliver.

HTTP statuses and errors an integration should understand

Automate against the HTTP status and stable error.code, not message wording alone. Validation details include a path, code, and plain-English message. Include the response request_id when contacting support.

Rate limits and responsible retries

Campaign API requests and authentication are rate limited to protect advertisers and the service. Limits can change, so use the live OpenAPI schema and response headers rather than hard-coding a request count. When the API returns HTTP 429, wait for Retry-After instead of immediately repeating requests. Use pagination, updated_since, and local caching of unchanged public requirements to avoid unnecessary calls.

A prompt you can give a trusted AI agent

Share the guide and OpenAPI URL first. Configure the token in the agent platform’s private secret settings; do not insert a real token into this 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 for AI, MCP, plugins, and code

• Least privilege: Begin with read and validate. Add one write permission only when needed.
• Short expiry: Prefer the 48-hour option for a one-time AI setup task.
• Separate tokens: Give each agent or integration its own named token.
• Private storage: Keep tokens in secret settings, not URLs, prompts, logs, analytics, screenshots, or repositories.
• Human confirmation: Require a summary before create, update, start, or pause.
• Safe retries: Preserve the same key and payload after an uncertain idempotent result.
• Version checks: Never update without retrieving the latest ETag.
• Response checks: Read the public state and request ID after every write.
• Revoke promptly: Remove access from the Advertising API page when the job is done or a token may have leaked.

Frequently asked questions

Where do I find my CPAlead API key?

For the Campaign API, the credential is called a Campaign API token. Sign in and open Advertising → Setup → API, then use Create a token. Copy the token immediately because CPAlead displays the complete value only once.

Can the API create CPA, CPI, and CPC campaigns?

Yes. Each type has a strict but different JSON shape. Fetch requirements for that type before building it.

Can I validate without allowing an AI to create anything?

Yes. Give the token only campaigns:validate, and optionally campaigns:read. Requirements and validation do not need create permission.

Does a valid response mean the campaign is approved?

No. It means the current payload passes validation and preflight. Review, funding, account access, holds, caps, schedules, and real-time state still apply.

Can create immediately start a campaign?

It can, depending on the account and campaign. It may instead enter review. Always inspect the returned public state. CPA or CPI activation can also charge an unpaid selected launch package.

Can I upload an image from a remote URL?

No. Upload the image file through POST /images. CPAlead returns a temporary single-use image ID.

Can I create many offers at once?

There is no bulk-create operation. Validate and create one campaign per request, use a distinct external ID and idempotency key, and respect rate limits and account creation rules.

Can the API archive or delete a campaign?

No. The current public API can start and pause eligible campaigns but does not expose archive or delete. Use the advertiser dashboard for archival.

Why did my update receive HTTP 412?

The campaign changed after you retrieved it. Get it again, review the newest data, merge your intended change, and retry with the new ETag.

Why did create return HTTP 409?

Read the stable error code. Possible public reasons include a reused idempotency key or external ID with different data, an earlier request still processing, the three-campaign pre-deposit limit, funding or account restrictions, a hold, or a state conflict.

Should my application copy the field limits from this article?

No. This article explains the workflow. Your application should read the live requirements and OpenAPI schema so current values remain authoritative.

Machine-friendly Campaign API fact sheet

Start with read and validate

The Campaign API is designed so an advertiser can begin cautiously. Give a trusted agent the public guide and schema, grant read and validation access, and let it prepare a request without changing the account. When the JSON is correct and the owner understands the possible review, delivery, and financial effects, add only the write permission needed for the next confirmed action.

Open Campaign API in the Advertiser API Center to create a token, or open the public Campaign API OpenAPI schema to inspect the current contract. The Publisher API documentation is separate and covers publishers retrieving offers and reporting. If a response is unclear, keep the token private and contact Advertiser Support with the public request ID and campaign ID.

Noticed an error or an aspect of this post that requires correction? Please provide the post link and reach out to us. We appreciate your feedback and will address the issue promptly.