Record events and conversions

Your product knows things ReputeCast doesn’t: a trial started, a plan was upgraded, an order was paid. Two endpoints bring those facts in. API events start and steer automations. The conversion tracking API records what an action was worth and credits it to the campaign or automation email the reader clicked, so revenue shows up next to your emails.

Before you begin

• An API key. API events need subscribers:edit. Conversions need conversions:create; the Conversions key preset in Settings › , then Keys & MCP holds that permission and nothing else and expires after 1 year by default. Create a conversions key under Earn › , then Settings › , then Attribution opens the same dialog.
• The contact must already exist in the workspace. Neither endpoint creates contacts; use Create or update a contact first.

Send an API event

POST /api/v1/workspaces/<workspace>/automations/events records an event for one contact:

Terminal

# REPUTECAST_API_KEY: an API key (rc_live_…) with subscribers:edit.
# Replace reputecast.example.com with your public URL and your-workspace with your workspace slug.
curl --request POST \
  --url https://reputecast.example.com/api/v1/workspaces/your-workspace/automations/events \
  --header "Authorization: Bearer $REPUTECAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "event": "trial.started",
    "email": "sam.rivera@outlook.com",
    "properties": { "plan": "team", "trial_days": 14 }
  }'

• event names it: letters, numbers and . _ : -, starting with a letter or number, up to 100 characters (trial.started, workspace.created).
• Say who it is about with email or contactId. An unknown address answers 404: add the contact first.
• properties is any JSON object up to 16 KB.

The answer is 202 with the contact and the number of live automations the event starts:

202 Accepted

{ "accepted": true, "contactId": "0192f1c4-3a5b-7c2d-8e9f-1a2b3c4d5e6f", "flows": 1 }

Use the event in an automation

1. In Automations, open a flow and set its trigger to API event.

2. Type the same Event name your product sends, for example trial.started. The match is exact.

3. Publish the flow. Contacts enroll within seconds of each event.

Goals and branches can wait for an event too, with the Sent an API event condition. The full list of triggers and steps is in Triggers and steps.

Events are contact activity, like opens and clicks, so they don’t appear in the audit log. Each call records a new event: don’t retry a call that was answered 202.

Record a conversion

POST /api/v1/workspaces/<workspace>/conversions records something valuable a reader did in your product:

Terminal

# REPUTECAST_API_KEY: an API key (rc_live_…) with conversions:create.
# Replace reputecast.example.com with your public URL and your-workspace with your workspace slug.
# Add "click_token" with the rc_click value of the link the reader followed, when you have it.
curl --request POST \
  --url https://reputecast.example.com/api/v1/workspaces/your-workspace/conversions \
  --header "Authorization: Bearer $REPUTECAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042' \
  --data '{
    "name": "Upgraded to Team plan",
    "value": "29.00",
    "currency": "USD",
    "email": "sam.rivera@outlook.com",
    "metadata": { "order_id": "1042" }
  }'

Field	Required	What it holds
name	Yes	What happened, up to 120 characters: “Upgraded to Team plan”.
value	Yes	A decimal string, "29.00", not 29. No more decimals than the currency has.
currency	Yes	A three-letter ISO 4217 code: USD, EUR, JPY.
email	One of the two	The reader’s address.
click_token	One of the two	The rc_click value from the link the reader followed. See Pass the click token.
occurred_at	No	When it happened, as RFC 3339. Up to 30 days back; now when you leave it out.
metadata	No	Your own fields, kept with the conversion (up to 8 KB).

Send an Idempotency-Key header (up to 200 characters), such as your order ID. Sending the same key again with the same body answers with the first conversion instead of recording a second; the same key with a different body answers 409 idempotency_key_reused. Keys are remembered per API key.

The answer is 202 and says how the conversion was matched:

202 Accepted

{
  "id": "0192f1c4-9e21-7a40-8c3b-2d4f6a8b0c1e",
  "matched": "click_token",
  "credited": { "kind": "campaign", "id": "0192f0aa-1b2c-7d3e-9f40-5a6b7c8d9e0f", "name": "Weekly Digest #142" }
}

How a conversion is credited

ReputeCast credits a conversion to the last campaign or automation email the reader clicked within the attribution window: 7 days by default, 1–30 days under Earn › , then Settings › , then Attribution › , then Attribution window.

1. With a valid click_token, the email that carried the clicked link, when the click falls within the window before occurred_at. matched is click_token.
2. Otherwise, with an email that matches a contact: matched is email, and the conversion is credited to the last email that contact clicked within the window, if there is one.
3. Otherwise matched is none. The conversion is kept, credited to nothing.

When nothing is credited, the answer has no credited field.

A credited conversion fires the conversion.recorded webhook event (Webhook events). Conversions appear in Conversions log and as product conversions on the revenue overview; they don’t count toward MRR (Revenue metrics explained).

Pass the click token

Matching by email only works when the reader is a known contact who clicked. The click token also works when the reader signs up with another address:

1. Turn on Click token on your own domains and add the domains of your product, such as app.example.com.

2. Links in your emails to those domains then carry rc_click=…. The token is opaque and signed, and it is never added to links to other domains, sponsor links included.

3. In your product, read rc_click from the landing URL and keep it with the visitor (for example, in their session or on the signup record).

4. Send it as click_token when the conversion happens. A token older than the attribution window no longer credits anything.

Errors and limits

• 422 missing_identity: send email, click_token or both.
• 422 invalid_value: send the value as a decimal string with no more decimals than the currency allows.
• 422 invalid_currency: use a three-letter ISO 4217 code.
• 422 occurred_at_out_of_range: occurred_at is more than 30 days ago or in the future.
• 409 idempotency_key_reused: the key came with a different body.
• 429 rate_limited: each key records up to 600 conversions per minute; wait for Retry-After.

Every code is listed in Errors.

Check that it worked

• Under Earn › , then Settings › , then Attribution, Send a test conversion records a test conversion for your own address. Your product’s conversions show up in Conversions log, newest first.
• An API event’s answer says how many live flows it started (flows). The automation’s step statistics show the contact entering.

Troubleshooting

• matched: "none" or no credited: the reader didn’t click an email within the window, or the address isn’t a contact. Pass the click token, or widen the window.
• flows: 0: no live automation has an API event trigger with exactly this event name. Check the spelling and that the flow is published.
• 404 on an API event: the contact doesn’t exist; create it first.
• Duplicate conversions: send an Idempotency-Key and reuse it on retries.

Related

Earn from your newsletterPaid subscriptions, revenue and attribution.

Build automationsFlows that react to your product's events.

Build an integrationContacts, lists, tags and events from other tools.

API referenceThe create-conversion operation in full.