Skip to content

Get an action

GET
/actions/{action_id}
curl --request GET \
--url https://api.poweredbyaura.com/v1/actions/act_01JAC4X9M2T7R9F3H6K8P1D5QS \
--header 'Authorization: Bearer <token>'
action_id
required
string

Example

act_01JAC4X9M2T7R9F3H6K8P1D5QS

The action, with its outcome and rewards as they are 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.

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.

Nothing with this ID exists in your account, in this mode (test or live).

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

ExamplenotFound
{
"error": {
"code": "not_found",
"message": "No customer with ID 'CUS-204871' has been reported to this campaign.",
"retryable": false,
"request_id": "req_5Nk3Ry8BwH1c"
}
}
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.