Skip to content

List campaigns

GET
/campaigns
curl --request GET \
--url 'https://api.poweredbyaura.com/v1/campaigns?status=draft&limit=25' \
--header 'Authorization: Bearer <token>'

Returns your campaigns, newest first. Campaigns are built and changed in the dashboard.

status

draft: being built. testing: takes actions from test keys only. live: takes actions from live keys and delivers data. paused: takes actions, which count in results but earn nothing. ended: takes actions for 8 weeks after it ends, to show whether the habit stuck, and earns nothing.

string
Allowed values: draft testing live paused ended
limit
integer
default: 25 >= 1 <= 100

Items per page, from 1 to 100.

cursor
string

The next_cursor from the previous page.

A page of campaigns.

Media typeapplication/json
object
object
required
string
Allowed value: list
data
required
Array<object>
object
id
required
string
object
required
string
Allowed value: campaign
name
required

Your internal name for the campaign.

string
plan_name
required

What customers see, such as “Your 6GB plan from [App]”.

string
status
required

draft: being built. testing: takes actions from test keys only. live: takes actions from live keys and delivers data. paused: takes actions, which count in results but earn nothing. ended: takes actions for 8 weeks after it ends, to show whether the habit stuck, and earns nothing.

string
Allowed values: draft testing live paused ended
starts_with
required

How a customer’s plan starts. action: after the action marked starts_plan, such as a first deposit. offer: by an offer you send with POST /offers, with no action needed first.

string
Allowed values: action offer
version
required

Changing a reward starts a new version, so customers in one version are treated the same.

integer
cadence
required

How often the plan’s data arrives, and so how long each period is.

string
Allowed values: daily weekly monthly
monthly_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
delivery_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
periods
required

How many periods a customer can hold the plan.

integer
actions
required
Array<object>
object
key
required

The name your developers send in action.

string
name
required

The readable name shown in the dashboard.

string
starts_plan
required

Whether this action starts a customer’s plan. Always false in a campaign that starts plans by offer.

boolean
keeps_plan
required

Whether this action keeps the plan for the period it happens in.

boolean
result
required

Whether this is the plan’s result, the action the plan exists to grow.

boolean
referral
required

Whether this action is a referral, sent with the friend who did it.

boolean
condition
required

The least the action must carry to count, when the plan sets one. Below it, the action earns nothing.

object
minimum_amount
object
amount
required

Amount in the currency’s minor unit (kobo for NGN).

integer
currency
required

ISO 4217 currency code.

string
/^[A-Z]{3}$/
minimum_count
integer
first_action_gb
required

A one-off reward for the action that starts the plan, when the plan has one.

number | null
referral_gb
required

What the customer and the friend each earn for a referral, when the plan has referrals.

number | null
grows
required

The plan’s bigger size, when a plan that grows is switched on. Off by default.

object
after_periods
required
integer
delivery_gb
required

An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.

number
multiple of 0.01
comparison_share
required

The share of new customers placed in the comparison group, from 0 to 0.5. 0 when it is off.

number
<= 0.5
launched_at
required
string | null format: date-time
ends_at
required
string | null format: date-time
has_more
required
boolean
next_cursor
required
string | null

Example

{
"object": "list",
"data": [
{
"object": "campaign",
"status": "draft",
"starts_with": "action",
"cadence": "daily",
"actions": [
{
"key": "weekly_deposit",
"name": "Weekly deposit"
}
]
}
]
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

The request is malformed or a field is invalid. Fix it before retrying.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExampleinvalidPhoneNumber
{
"error": {
"code": "invalid_phone_number",
"message": "phone_number must be in E.164 format, such as +2348000000001.",
"param": "phone_number",
"retryable": false,
"request_id": "req_9Qd4Hs1XvB7n"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

The API key is missing, wrong or revoked.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExampleinvalidKey
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, wrong or revoked.",
"retryable": false,
"request_id": "req_4Lm8Tc2VqZ7k"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

Too many requests. Wait for Retry-After seconds, then retry.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable code. New codes may be added in v1, so treat an unknown code by its HTTP status and retryable flag. The first block is shared with the Data Reselling API.

string
Allowed values: invalid_request invalid_phone_number invalid_api_key ip_not_allowed not_found reference_conflict rate_limited internal_error unknown_campaign unknown_action campaign_not_live campaign_required plan_not_offered already_accepted already_offered campaign_starts_with_action number_change_too_soon number_on_another_plan
message
required

A human-readable explanation. Do not parse it; use code.

string
param

The request field the error is about, when there is one.

string
retryable
required

Whether the same request can succeed if you retry it later.

boolean
request_id
required
string
details

Extra facts about the error, such as the existing action.

object
key
additional properties
any

Examples

ExamplerateLimited
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 seconds.",
"retryable": true,
"request_id": "req_2Vb7Nx4KtJ9q"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

A unique ID for this request. Quote it when you contact Aura.

RateLimit-Limit
integer

Requests allowed in the current window.

RateLimit-Remaining
integer

Requests left in the current window.

RateLimit-Reset
integer

Seconds until the current window resets.

Retry-After
integer

Seconds to wait before retrying.