Skip to content

Report an action

POST
/actions
curl --request POST \
--url https://api.poweredbyaura.com/v1/actions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "reference": "dep-889431", "campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA", "action": "weekly_deposit", "customer_id": "CUS-204871", "phone_number": "+2348000000001", "occurred_at": "2026-10-20T09:40:00+01:00", "value": { "amount": { "amount": 1000000, "currency": "NGN" } }, "source": "app" }'

Reports one thing a customer did. Send every action named in the campaign, for every customer you report, including customers in the comparison group and customers whose plan has ended: actions that earn nothing still count in your results.

The response says at once whether the action earned data (earned) and, if not, why (reason). A reward that was earned is delivered afterwards; follow it with the reward.delivered and reward.failed webhooks or by looking it up.

reference is your own unique ID for the action and makes the request safe to retry. Sending the same reference with the same body returns the original action with status 200 and the header Aura-Idempotent-Replay: true, and never pays twice. Sending it with a different body returns 409 reference_conflict.

Taking in an action never depends on a network being up. If a network is unavailable, the reward waits and is delivered when the network is back, or fails and releases its hold.

Media typeapplication/json
object
reference
required

Your unique ID for this action. Letters, numbers, -, _, . and :, up to 64 characters.

string
/^[A-Za-z0-9._:-]{1,64}$/
campaign_id
required
string
action
required

The action’s key, as set in the campaign.

string
customer_id
required

Your own ID for the customer. Up to 64 characters. Never send names.

string
<= 64 characters
phone_number
required

The customer’s number on your records, in E.164 format. When they accept the plan, they can choose another of their numbers for the data.

string
occurred_at
required

When the customer did it, with a UTC offset. The action counts in the period it happened in, if it arrives within 2 hours after that period ends. Times more than 5 minutes in the future are refused.

string format: date-time
value

What the action carried, when the plan sets a condition such as a minimum deposit or a number of transactions.

object
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}$/
count
integer
source

Optional. Where the customer came from, such as an ad with the plan offer, so the results can show the cost per new customer for each source.

string
<= 64 characters
friend

For a referral action only. The friend who did the qualifying action.

object
customer_id
required
string
<= 64 characters
phone_number
required
string
metadata

Up to 20 keys of your own, returned on the action and in webhooks. Values are strings of up to 500 characters.

object
<= 20 properties
key
additional properties
string
<= 500 characters

Examples

A weekly deposit of ₦10,000

{
"reference": "dep-889431",
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"action": "weekly_deposit",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"occurred_at": "2026-10-20T09:40:00+01:00",
"value": {
"amount": {
"amount": 1000000,
"currency": "NGN"
}
},
"source": "app"
}

An action with this reference and the same body already exists. It is returned as it is now.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: action
reference
required
string
campaign_id
required
string
action
required
string
customer_id
required
string
phone_number
required
string
occurred_at
required
string format: date-time
received_at
required
string format: date-time
value
object
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}$/
count
integer
source
string | null
friend
object
customer_id
string
phone_number
string
group
required

The customer’s group, set at random the first time you report them. Don’t show the plan to customers in the comparison group, but keep sending their actions.

string
Allowed values: offer comparison
earned
required

Whether the action earned data under the plan’s rules. It can change once, from true to false, when a flagged reward is rejected in review or the customer doesn’t accept the plan in time.

boolean
reason
required
One of:

Why an action earned no data. New reasons may be added in v1.

comparison_group: the customer is in the comparison group; the action is recorded and nothing is paid. already_rewarded: this period’s reward was already earned. number_already_rewarded: another customer ID on this phone number already earned this reward this period. condition_not_met: the action carried less than the plan’s condition. not_eligible: the plan is only for customers first reported after it started. no_plan: a keep action for a customer whose plan hasn’t started. plan_cancelled: the plan cancelled after a missed period. plan_ended: the customer has held the plan for its full length. too_late: the action arrived after its period closed; it still counts in results. customer_limit_reached and daily_limit_reached: a campaign limit was reached. budget_reached: the campaign’s budget is spent. campaign_paused and campaign_ended: the campaign isn’t live. referral_not_allowed: a self-referral, a friend on the customer’s own number, or a friend who was already a customer. friend_limit_reached: the customer has brought the most friends the plan allows. rejected_in_review: a flagged reward was rejected in review. customer_not_accepted: the customer didn’t accept the plan before the period ended.

string
Allowed values: comparison_group already_rewarded number_already_rewarded condition_not_met not_eligible no_plan plan_cancelled plan_ended too_late customer_limit_reached daily_limit_reached budget_reached campaign_paused campaign_ended referral_not_allowed friend_limit_reached rejected_in_review customer_not_accepted
rewards
required

The rewards this action earned. A referral earns one for the customer and one for the friend.

Array<object>
object
id
required
string
object
required
string
Allowed value: reward
customer_id
required

Who receives it. For a referral, one reward is the customer’s and one is the friend’s.

string
kind
required

plan_delivery: a period’s data. first_action: a one-off reward for starting the plan. referral: a referral reward.

string
Allowed values: plan_delivery first_action referral
amount_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
status
required

waiting_for_customer: earned, waiting for the customer to accept the plan. flagged: waiting for review. waiting_for_balance: your balance doesn’t cover it; it waits up to 24 hours for a top-up, then fails. pending: its price is held and the delivery is on its way. delivered: the network confirmed it and your balance was charged. failed: not delivered, nothing charged. reversed: the network reversed a delivery and you were refunded. rejected: rejected in review, or lapsed because the customer didn’t accept the plan.

string
Allowed values: waiting_for_customer flagged waiting_for_balance pending delivered failed reversed rejected
plan
required
One of:
object
id
required
string
object
required
string
Allowed value: plan
status
required

not_offered: the customer is in the comparison group. offered: the plan was offered, after its start action or by an offer, and waits for the customer to accept. active: accepted, and this period is kept or still open. at_risk: the warning has gone out and this period’s action isn’t in yet. cancelled: a period ended without its action. ended: the customer held the plan for its full length, or the campaign ended.

string
Allowed values: not_offered offered active at_risk cancelled ended
current_period
required
object
ends_at
required
string format: date-time
kept
required
boolean
test
required

true when sent with a test key.

boolean
metadata
required
object
key
additional properties
string

Examples

Exampleearned

Earned this week's 1.5GB

{
"id": "act_01JAC4X9M2T7R9F3H6K8P1D5QS",
"object": "action",
"reference": "dep-889431",
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"action": "weekly_deposit",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"occurred_at": "2026-10-20T08:40:00Z",
"received_at": "2026-10-20T08:40:02Z",
"value": {
"amount": {
"amount": 1000000,
"currency": "NGN"
}
},
"source": "app",
"friend": null,
"group": "offer",
"earned": true,
"reason": null,
"rewards": [
{
"id": "rwd_01JAC4X9M2T7R9F3H6K8P1D5QT",
"object": "reward",
"customer_id": "CUS-204871",
"kind": "plan_delivery",
"amount_gb": 1.5,
"status": "pending"
}
],
"plan": {
"id": "pln_01JAC4XB7Q2W9D8M5X4N6B1C0V",
"object": "plan",
"status": "active",
"current_period": {
"ends_at": "2026-10-25T22:59:59Z",
"kept": true
}
},
"test": false,
"metadata": {}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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

Aura-Idempotent-Replay
string
Allowed value: true

Always true on a replayed response.

The action was recorded. earned says whether it earned data.

Media typeapplication/json
object
id
required
string
object
required
string
Allowed value: action
reference
required
string
campaign_id
required
string
action
required
string
customer_id
required
string
phone_number
required
string
occurred_at
required
string format: date-time
received_at
required
string format: date-time
value
object
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}$/
count
integer
source
string | null
friend
object
customer_id
string
phone_number
string
group
required

The customer’s group, set at random the first time you report them. Don’t show the plan to customers in the comparison group, but keep sending their actions.

string
Allowed values: offer comparison
earned
required

Whether the action earned data under the plan’s rules. It can change once, from true to false, when a flagged reward is rejected in review or the customer doesn’t accept the plan in time.

boolean
reason
required
One of:

Why an action earned no data. New reasons may be added in v1.

comparison_group: the customer is in the comparison group; the action is recorded and nothing is paid. already_rewarded: this period’s reward was already earned. number_already_rewarded: another customer ID on this phone number already earned this reward this period. condition_not_met: the action carried less than the plan’s condition. not_eligible: the plan is only for customers first reported after it started. no_plan: a keep action for a customer whose plan hasn’t started. plan_cancelled: the plan cancelled after a missed period. plan_ended: the customer has held the plan for its full length. too_late: the action arrived after its period closed; it still counts in results. customer_limit_reached and daily_limit_reached: a campaign limit was reached. budget_reached: the campaign’s budget is spent. campaign_paused and campaign_ended: the campaign isn’t live. referral_not_allowed: a self-referral, a friend on the customer’s own number, or a friend who was already a customer. friend_limit_reached: the customer has brought the most friends the plan allows. rejected_in_review: a flagged reward was rejected in review. customer_not_accepted: the customer didn’t accept the plan before the period ended.

string
Allowed values: comparison_group already_rewarded number_already_rewarded condition_not_met not_eligible no_plan plan_cancelled plan_ended too_late customer_limit_reached daily_limit_reached budget_reached campaign_paused campaign_ended referral_not_allowed friend_limit_reached rejected_in_review customer_not_accepted
rewards
required

The rewards this action earned. A referral earns one for the customer and one for the friend.

Array<object>
object
id
required
string
object
required
string
Allowed value: reward
customer_id
required

Who receives it. For a referral, one reward is the customer’s and one is the friend’s.

string
kind
required

plan_delivery: a period’s data. first_action: a one-off reward for starting the plan. referral: a referral reward.

string
Allowed values: plan_delivery first_action referral
amount_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
status
required

waiting_for_customer: earned, waiting for the customer to accept the plan. flagged: waiting for review. waiting_for_balance: your balance doesn’t cover it; it waits up to 24 hours for a top-up, then fails. pending: its price is held and the delivery is on its way. delivered: the network confirmed it and your balance was charged. failed: not delivered, nothing charged. reversed: the network reversed a delivery and you were refunded. rejected: rejected in review, or lapsed because the customer didn’t accept the plan.

string
Allowed values: waiting_for_customer flagged waiting_for_balance pending delivered failed reversed rejected
plan
required
One of:
object
id
required
string
object
required
string
Allowed value: plan
status
required

not_offered: the customer is in the comparison group. offered: the plan was offered, after its start action or by an offer, and waits for the customer to accept. active: accepted, and this period is kept or still open. at_risk: the warning has gone out and this period’s action isn’t in yet. cancelled: a period ended without its action. ended: the customer held the plan for its full length, or the campaign ended.

string
Allowed values: not_offered offered active at_risk cancelled ended
current_period
required
object
ends_at
required
string format: date-time
kept
required
boolean
test
required

true when sent with a test key.

boolean
metadata
required
object
key
additional properties
string

Examples

Earned this week's 1.5GB

{
"id": "act_01JAC4X9M2T7R9F3H6K8P1D5QS",
"object": "action",
"reference": "dep-889431",
"campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA",
"action": "weekly_deposit",
"customer_id": "CUS-204871",
"phone_number": "+2348000000001",
"occurred_at": "2026-10-20T08:40:00Z",
"received_at": "2026-10-20T08:40:02Z",
"value": {
"amount": {
"amount": 1000000,
"currency": "NGN"
}
},
"source": "app",
"friend": null,
"group": "offer",
"earned": true,
"reason": null,
"rewards": [
{
"id": "rwd_01JAC4X9M2T7R9F3H6K8P1D5QT",
"object": "reward",
"customer_id": "CUS-204871",
"kind": "plan_delivery",
"amount_gb": 1.5,
"status": "pending"
}
],
"plan": {
"id": "pln_01JAC4XB7Q2W9D8M5X4N6B1C0V",
"object": "plan",
"status": "active",
"current_period": {
"ends_at": "2026-10-25T22:59:59Z",
"kept": true
}
},
"test": false,
"metadata": {}
}
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.

An action with this reference exists with a different body. Nothing was recorded.

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

ExamplereferenceConflict
{
"error": {
"code": "reference_conflict",
"message": "An action with reference 'dep-889431' already exists with a different customer_id.",
"retryable": false,
"request_id": "req_3Fh8Lw2NcY6d",
"details": {
"action_id": "act_01JAC4X9M2T7R9F3H6K8P1D5QS"
}
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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

The request is well formed but can’t be recorded: the campaign or action isn’t known, or the campaign can’t take actions with this key. Nothing was recorded.

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

{
"error": {
"code": "unknown_action",
"message": "Action 'weekly_deposits' isn't defined on this campaign. Defined actions: first_deposit, weekly_deposit, friend_first_deposit.",
"param": "action",
"retryable": false,
"request_id": "req_8Wc2Lm5TzQ1v"
}
}
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.

Something went wrong on Aura’s side. Retry with the same reference; it is safe.

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

Exampleinternal
{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry with the same reference.",
"retryable": true,
"request_id": "req_6Gt1Mz5RcW3p"
}
}
Aura-Request-Id
string
Example
req_7Kp2Vx9QmR4t

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