Report an action
const url = 'https://api.poweredbyaura.com/v1/actions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Your unique ID for this action. Letters, numbers, -, _, . and :, up to 64 characters.
The action’s key, as set in the campaign.
Your own ID for the customer. Up to 64 characters. Never send names.
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.
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.
What the action carried, when the plan sets a condition such as a minimum deposit or a number of transactions.
object
object
Amount in the currency’s minor unit (kobo for NGN).
ISO 4217 currency code.
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.
For a referral action only. The friend who did the qualifying action.
object
Up to 20 keys of your own, returned on the action and in webhooks. Values are strings of up to 500 characters.
object
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"}A referral, sent for the customer who invited the friend
{ "reference": "ref-120554", "campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA", "action": "friend_first_deposit", "customer_id": "CUS-204871", "phone_number": "+2348000000001", "occurred_at": "2026-10-20T10:05:00+01:00", "value": { "amount": { "amount": 500000, "currency": "NGN" } }, "friend": { "customer_id": "CUS-311902", "phone_number": "+2348000000002" }}Responses
Section titled “Responses”An action with this reference and the same body already exists. It is returned as it is now.
object
object
object
Amount in the currency’s minor unit (kobo for NGN).
ISO 4217 currency code.
object
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.
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.
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.
The rewards this action earned. A referral earns one for the customer and one for the friend.
object
Who receives it. For a referral, one reward is the customer’s and one is the friend’s.
plan_delivery: a period’s data. first_action: a one-off reward for starting the plan. referral: a referral reward.
An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.
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.
object
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.
object
true when sent with a test key.
object
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": {}}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
Always true on a replayed response.
The action was recorded. earned says whether it earned data.
object
object
object
Amount in the currency’s minor unit (kobo for NGN).
ISO 4217 currency code.
object
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.
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.
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.
The rewards this action earned. A referral earns one for the customer and one for the friend.
object
Who receives it. For a referral, one reward is the customer’s and one is the friend’s.
plan_delivery: a period’s data. first_action: a one-off reward for starting the plan. referral: a referral reward.
An amount of mobile data in gigabytes (GB), as set in the plan, to at most two decimal places.
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.
object
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.
object
true when sent with a test key.
object
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": {}}A second deposit in the same week
{ "id": "act_01JAC5D2W8K4M7T1R6F9H3P2QN", "object": "action", "reference": "dep-889502", "campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA", "action": "weekly_deposit", "customer_id": "CUS-204871", "phone_number": "+2348000000001", "occurred_at": "2026-10-22T14:10:00Z", "received_at": "2026-10-22T14:10:01Z", "value": { "amount": { "amount": 750000, "currency": "NGN" } }, "source": null, "friend": null, "group": "offer", "earned": false, "reason": "already_rewarded", "rewards": [], "plan": { "id": "pln_01JAC4XB7Q2W9D8M5X4N6B1C0V", "object": "plan", "status": "active", "current_period": { "ends_at": "2026-10-25T22:59:59Z", "kept": true } }, "test": false, "metadata": {}}A customer in the comparison group
{ "id": "act_01JAC5F7N3Q8T2W6K9M4R1D5HX", "object": "action", "reference": "dep-889517", "campaign_id": "cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA", "action": "first_deposit", "customer_id": "CUS-205114", "phone_number": "+2348000000003", "occurred_at": "2026-10-20T11:02:00Z", "received_at": "2026-10-20T11:02:01Z", "value": { "amount": { "amount": 2000000, "currency": "NGN" } }, "source": "app", "friend": null, "group": "comparison", "earned": false, "reason": "comparison_group", "rewards": [], "plan": null, "test": false, "metadata": {}}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
The request is malformed or a field is invalid. Fix it before retrying.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
Examples
{ "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" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
The API key is missing, wrong or revoked.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
Examples
{ "error": { "code": "invalid_api_key", "message": "The API key is missing, wrong or revoked.", "retryable": false, "request_id": "req_4Lm8Tc2VqZ7k" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
An action with this reference exists with a different body. Nothing was recorded.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
Examples
{ "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" } }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA 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.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
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" }}{ "error": { "code": "campaign_not_live", "message": "This campaign is in Testing. Send test actions with a test key until it goes live.", "param": "campaign_id", "retryable": false, "request_id": "req_6Rb9Xn3KpD2s" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
Too many requests. Wait for Retry-After seconds, then retry.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
Examples
{ "error": { "code": "rate_limited", "message": "Too many requests. Retry after 2 seconds.", "retryable": true, "request_id": "req_2Vb7Nx4KtJ9q" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
Requests allowed in the current window.
Requests left in the current window.
Seconds until the current window resets.
Seconds to wait before retrying.
Something went wrong on Aura’s side. Retry with the same reference; it is safe.
object
object
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.
A human-readable explanation. Do not parse it; use code.
The request field the error is about, when there is one.
Whether the same request can succeed if you retry it later.
Extra facts about the error, such as the existing action.
object
Examples
{ "error": { "code": "internal_error", "message": "Something went wrong on our side. Retry with the same reference.", "retryable": true, "request_id": "req_6Gt1Mz5RcW3p" }}Headers
Section titled “Headers”Example
req_7Kp2Vx9QmR4tA unique ID for this request. Quote it when you contact Aura.
© 2026 PressOne Africa Limited ·poweredbyaura.com ·Privacy ·Terms