Skip to content

Reporting actions

Send one call to POST /actions each time a customer does something your campaign names, such as a weekly savings deposit. Aura checks the plan’s rules and answers straight away.

Report every action the campaign names, for every customer you report, including:

  • customers in the comparison group, who are never offered the plan;
  • customers whose plan has been cancelled or has ended;
  • actions in a week the customer has already kept.

Actions that earn nothing still count in your results. That is how the results show what the plan changed.

Field Required What it holds
reference Yes Your own unique ID for this action, up to 64 letters, numbers, -, _, . and :. It makes the call safe to retry.
campaign_id Yes The campaign, such as cmp_01JA9TQ4W2D8M5X4N6B1C0VEKA.
action Yes The action’s key, as set in the campaign, such as weekly_deposit.
customer_id Yes Your own ID for the customer, up to 64 characters. Never send names.
phone_number Yes The customer’s number on your records, in E.164 format, such as +2348000000001. When they accept the plan, they can choose another of their numbers for the data.
occurred_at Yes When the customer did it, in ISO 8601 with a UTC offset, such as 2026-10-20T09:40:00+01:00.
value When the plan sets a condition What the action carried: amount in kobo, or count. See Conditions.
source No Where the customer came from, such as the ad that showed them the plan, so results show the cost per new customer by source.
friend Referrals only The friend who did the qualifying action: their customer_id and phone_number.
metadata No Up to 20 keys of your own, returned on the action and in webhooks.
Terminal window
curl https://api.poweredbyaura.com/v1/actions \
-H "Authorization: Bearer $AURA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}'

Every new action returns 201, whether or not it earned data. Errors are only for a request that is wrong.

{
"id": "act_01JAC4X9M2T7R9F3H6K8P1D5QS",
"object": "action",
"reference": "dep-889431",
"action": "weekly_deposit",
"customer_id": "CUS-204871",
"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 }
},
…
}
Field What it tells you
earned Whether the action earned data under the plan’s rules.
reason Why it earned nothing, when earned is false. See the table below.
rewards What it earned. A referral earns one reward for the customer and one for the friend.
plan The customer’s plan after this action, or null when they have none in this campaign.
group offer or comparison, set at random the first time you report the customer.

A reward that was earned is delivered afterwards. Follow it with the reward.delivered and reward.failed webhooks, or look it up.

earned can change once, from true to false: when a flagged reward is rejected in review, or when the customer doesn’t accept the plan in time. You get reward.rejected when it does.

reason What it means
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, such as a deposit below the minimum.
not_eligible The plan is only for customers first reported after it started.
no_plan An action that keeps a plan, for a customer whose plan hasn’t started.
plan_cancelled The plan was 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 your results.
customer_limit_reached The customer reached the campaign’s limit per customer.
daily_limit_reached The campaign reached its limit for the day.
budget_reached The campaign’s budget is spent.
campaign_paused, 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.

New reasons may be added within v1. Treat a reason you don’t know as “earned nothing”.

A plan can set the least an action must carry to count, such as a deposit of at least ₦5,000 or 50 payments. The campaign’s actions show it in condition. Send what the action carried in value:

Condition Send Example
An amount, such as a deposit of at least ₦5,000 value.amount, in kobo, with the currency NGN A ₦10,000 deposit: "value": { "amount": { "amount": 1000000, "currency": "NGN" } }
A count, such as 50 payments in the week value.count "value": { "count": 52 }

Below the condition, the action earns nothing, with condition_not_met, and still counts in your results.

For a balance kept all week, send one action at the week’s end, with the week’s lowest balance as value.amount.

Send a referral action for the customer who invited the friend, with the friend in 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" }
}

A referral earns one reward for the customer and one for the friend. Each friend counts once.

An action counts in the period it happened in, by occurred_at, if it arrives within 2 hours after that period ends. So a deposit at 11:55pm on Sunday still keeps the week if your system sends it by 2am on Monday, Lagos time. Aura decides whether a week was kept, or the plan cancels, only when those 2 hours are up.

An action that arrives later earns nothing, with too_late, and still counts in your results. A time more than five minutes in the future is refused.

Your reference is the key that makes a retry safe, and it never expires:

  • The same reference with the same body returns the original action with 200 and the header Aura-Idempotent-Replay: true. Nothing is paid twice.
  • The same reference with a different body returns 409 reference_conflict. Nothing is recorded.

If a call times out or returns 500, send it again with the same reference. Taking in an action never depends on a network being up: if a network is down, the reward waits until it is back, or fails and releases its hold.

HTTP code What to fix
400 invalid_request, invalid_phone_number A field is missing or malformed. param names it.
401 invalid_api_key The key is missing, wrong or revoked, or for the other environment.
409 reference_conflict The reference belongs to a different action. details.action_id names it.
422 unknown_campaign, unknown_action The campaign or action key isn’t defined. The message lists the campaign’s actions.
422 campaign_not_live The campaign is in testing: send test actions with a test key until it goes live.
429 rate_limited Wait for Retry-After seconds, then retry with the same reference.
500 internal_error Retry with the same reference; it is safe.

Every error code is in Errors.

Look an action up by your own reference with GET /actions?reference=dep-889431, or by Aura’s ID with GET /actions/{action_id}. Both return the action with its outcome and rewards as they are now.