API referenceGetting started

Quickstart

From nothing to a sale credited to a creator, in seven calls.

Before you start

Twenty minutes, one key, and no SDK. At the end a sale made by somebody who watched a video will be credited to the creator who made it, and you will be able to read that back.

Do this with a test key. The mode is carried on the key and never on the request, so a test key issues test codes, records test conversions and cannot touch anything live. Nothing below needs changing when you switch: you use a live key instead.

1. Open a campaign

A campaign is a destination. Pass your own id for it and you never have to store ours.

cURL
curl -X POST "https://track.acrune.com/v1/campaigns" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"cmp_4471","name":"January clips","destinationUrl":"https://yourapp.example/start"}'

Safe to call again with the same externalId: you get the campaign back rather than a second one pointed somewhere else.

2. Enrol a creator and get their link

Enrolling returns the creator's link. This is the call your own creator dashboard makes on every render, so it is idempotent on your externalId: calling it again returns the same link rather than splitting one person's clicks across several.

curl -X POST "https://track.acrune.com/v1/creators" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaignExternalId":"cmp_4471","externalId":"sa_8842","handle":"apexlaps","platform":"tiktok"}'

3. Issue a promo code

A link measures the people who tap. A code measures the people who do not, and on iOS that is most of them. Issue one per creator on the campaign.

cURL
curl -X POST "https://track.acrune.com/v1/promo-codes" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign":"cmp_4471","maxRedemptions":500}'

Cap them. Aggregators scrape and republish creator codes, and an uncapped code turns one scraped post into an unbounded claim on your budget.

4. Tap the link

Follow the link yourself to prove the chain. It answers 302 to your destination with a click id on the campaign's click parameter, which defaults to subid.

cURL
curl -sS -o /dev/null -D - "https://track.acrune.com/r/kp7r2wqm"
# location: https://yourapp.example/start?subid=8fk2xq...

If the destination is a Play Store URL you get the click id inside the store's referrer parameter instead, which Google hands to your app on first launch. That is the whole Android bridge and it needs no configuration; see Mobile and installs.

5. Bind the user at signup

At signup, hand us the click id and your own id for the user. This is the join that makes a purchase weeks later attributable, long after the browser that produced the click is gone.

cURL
curl -X POST "https://track.acrune.com/v1/identities" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clickId":"8fk2xq...","externalUserId":"usr_4471"}'

No click id, because they installed from the App Store or typed a code? Send what you do have to /v1/identities/self-reported instead. It records the claim at a weaker tier and never overwrites a binding a real tap already made.

6. Report the sale

Report the sale from your own backend. Send the strongest thing you have: a click id if the checkout carried one, the code if they typed one, and otherwise just your user id, which resolves through the binding from step 5.

curl -X POST "https://track.acrune.com/v1/conversions" \
  -H "Authorization: Bearer $ACRUNE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"usr_4471","idempotencyKey":"ord_88412","kind":"purchase","grossMinor":4900,"currency":"USD"}'

idempotencyKey must be stable for the same real-world event: the order id, the subscription id, or the user id for a once-per-person event like signup. A retry that changes it credits a creator twice, which is why it is required rather than defaulted.

7. Read it back

That attribution object is the answer. accountId is the creator who earned it, tier says on what evidence, and state says whether it is settled or waiting on a person.

attribution: null is not an error. The sale is real and you still made it; it simply credits nobody, which happens whenever none of the three claims resolves. A client that retries on null will report the same sale forever.

cURL
curl "https://track.acrune.com/v1/campaigns/cmp_4471/stats" \
  -H "Authorization: Bearer $ACRUNE_KEY"

When nothing is attributed

Work down these in order. They are the four things that actually go wrong, most common first.

  1. attribution came back null with a code. Call POST /v1/promo-codes/{code}/validate: the reason will be unknown, disabled or exhausted, and all three are answers rather than faults.

  2. attribution came back null with an externalId. Nothing was bound at signup, so step 5 did not run or ran without a click id. Binding is what step 5 buys you and there is no way to add it after the fact.

  3. A 401 or a 404, and which one you got is the answer. A 401 means your key is wrong and tells you nothing about the path, because /v1 authenticates before it routes. A 404 means the path is wrong and tells you your key is fine. Probe with a working key and a control path you know is invented, and the pair distinguishes them.

  4. A 403 rather than a 401. The key is valid and lacks the scope. Write implies read, money implies both, and issuing the narrowest scope that does the job is the right habit even though it produces this.

Everything above is exercised as one sequence by our own test suite, over HTTP against the real schema, so a step that stops working fails our build rather than your integration.