Create Campaign

Creates a new marketing campaign with tracking and spend settings.

Required Fields

campaign_name — must be unique within the organization

org_unit_id — must reference an existing, active organization unit

start_date — campaign start date/time (ISO 8601 format)

timezone — IANA timezone (e.g., "America/New_York")

owner_user_id — user ID who owns this campaign

campaign_spend — campaign budget amount

conversion_value — target conversion value

campaign_spend_frequency — "one_time" or "monthly"

Optional Fields

end_date — campaign end date/time (ISO 8601 format). Use null or "never" for campaigns with no end date

external_id — your own external/CRM identifier

status — defaults to "active" (options: active, inactive, deleted, suspended, referral)

referral_pnumber — referral phone number

Date/Time Handling

Dates are stored with timezone offset (e.g., "2026-06-01T09:00:00-04:00")

All date formats are interpreted in the specified timezone:

"2026-06-01T09:00:00" → treated as 9am in your timezone

"2026-06-01T09:00:00Z" → Z is stripped, treated as 9am in your timezone (NOT converted from UTC)

"2026-06-01T09:00:00-05:00" → offset stripped, treated as 9am in your timezone

DST (Daylight Saving Time) is handled automatically based on the date

Validation Rules

start_date cannot be before today (day-only check: same day with past time is allowed)

end_date must be >= start_date

Cannot create ACTIVE campaign with past end date/time

Auto-status behavior:

If start_date time is in the future → status automatically set to INACTIVE (campaign will auto-activate via scheduler)

If end_date time has already passed → status automatically set to INACTIVE

Both checks use datetime comparison (not just day)

Use status: "inactive" to create campaigns with past end dates (for historical tracking)

Business Rules

Future campaigns auto-activate on start_date/time via scheduled jobs

Trial accounts have campaign creation limits

Campaign creates both main record and spend tracking fields atomically

User must have access to the specified org_unit_id

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://platform-api.convirza.com/v3/campaigns' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "campaign_name": "Summer Sale 2026", "campaign_ext_id": 12345, "status": "active", "start_date": "2026-06-01T09:00:00", "end_date": "2026-08-31T17:00:00", "timezone": "America/New_York", "owner_user_id": 101, "org_unit_id": 1001, "campaign_spend": 5000, "conversion_value": 150, "campaign_spend_frequency": "one-time", "referral_pnumber": "1234567890" }'

{ "code": 200, "message": "Success", "data": { "campaign_id": 1, "campaign_name": "Summer Sale 2026", "external_id": 12345, "status": "active", "start_date": "2026-06-01T09:00:00-04:00", "end_date": "2026-08-31T17:00:00-04:00", "timezone": "America/New_York", "owner_user_id": 101, "org_unit_id": 1001, "referral_pnumber": "1234567890", "campaign_spend": 5000, "conversion_value": 150, "campaign_spend_frequency": "one_time", "created_at": "2026-01-15T15:30:00.000Z", "modified_at": "2026-03-20T18:45:00.000Z" }, "request_id": "550e8400-e29b-41d4-a716-446655440000", "timestamp": "2026-01-20T12:34:56.789Z" }

Create Campaign

Request

Responses