Ortto

Datafly Signal delivers your first-party events to Ortto server-side using the Custom Activity API. Each event upserts the person in Ortto (matched by email, with phone as a fallback) and records a timestamped custom activity against them, ready to drive journeys, segments, and reports.

Because delivery is server-to-server, no Ortto tracking pixel runs in the browser, and identity fields are sent from your own first-party data rather than scraped client-side.

Why route Ortto through Datafly Signal

• Profiles are updated from the server, not the browser. Events reach Ortto even when a tracker blocker or a failed page unload would have dropped a client-side call, so the profile reflects what actually happened.
• Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the Ortto rate limit, and retries on 429 or transient failure rather than dropping the event.
• Presets for Retail and B2B / SaaS. The mapping starts from a working configuration for your vertical instead of a blank field map.
• One consent decision governs every destination. Ortto is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

• An Ortto account with the Custom Activity API available on your plan.
• A custom (private) API key with activity write access. Create one in Ortto under Settings → API keys. This is not the public tracking-code key.
• One or more custom activity definitions created in Ortto (Activities → New activity). Each definition has an activity ID in the form act:cm:<slug> (for example act:cm:order-completed). You will map your Signal events to these IDs.
• Your Ortto instance region, which determines the API host (see below).

Configuration

Pick the host that matches the region your Ortto instance is pinned to. A mismatched region returns 401 or 404.

Configure in Signal

1. In the Signal management UI, go to Integrations and add Ortto.
2. Paste your Custom API Key and select the API Host for your region.
3. Choose a preset (Retail or B2B / SaaS) or start from the default mapping.
4. For each event in the preset, set vendor event name to the matching Ortto activity ID (act:cm:<slug>) from your Ortto activity definitions.
5. Attach the integration to your pipeline and publish.

API Endpoint

POST https://api.ap3api.com/v1/activities/create
X-Api-Key: <your-custom-api-key>
Content-Type: application/json

Australia and Europe instances use api.au.ap3api.com and api.eu.ap3api.com respectively.

Identity Signals

Server-side delivery to the Ortto Custom Activity API (/v1/activities/create). Each Signal event upserts the person by email (merge_by str::email; plain text, trimmed and lowercased, because Ortto keys the person on it) with first and last name and the source IP, and records a custom activity (act:cm:<event>) with typed attributes: text as str, money as int x1000, quantities as whole numbers. Events without an email are not sent.

Event Mapping

Blueprint 0.6.0, reviewed against the vendor’s documentation on 2026-09-23. Each preset maps the events below; every other event is dropped. Events use the canonical names from the event specs (transaction_id, value, items[], search_term); the legacy order_id, revenue and flat product fields are still read as a fallback.

Retail / E-commerce (ecommerce)

Retail funnel as Ortto custom activities: page viewed, product viewed and added, checkout started and order completed with the conversion value. Each activity upserts the person by email (merge_by str::email; str::email is sent in plain text, trimmed and lowercased, because Ortto keys the person on it; events without an email are not sent), with first and last name and the visitor IP for geo. Attribute types follow Ortto’s typed IDs: text as str:cm:, money and decimals as int x1000 (int::v, int:cm:price), quantities as whole numbers. Create each act:cm: activity and its attributes in Ortto first.

B2B / SaaS (saas)

Account lifecycle as Ortto custom activities: page viewed, signed up, logged in, trial and subscription started. Each activity upserts the person by email (merge_by str::email; str::email is sent in plain text, trimmed and lowercased, because Ortto keys the person on it; events without an email are not sent), with first and last name and the visitor IP for geo. Attribute types follow Ortto’s typed IDs: text as str:cm:, money and decimals as int x1000 (int::v, int:cm:price), quantities as whole numbers. Create each act:cm: activity and its attributes in Ortto first.

Default (default)

Page views, sign-ups and orders as Ortto custom activities. Each activity upserts the person by email (merge_by str::email; str::email is sent in plain text, trimmed and lowercased, because Ortto keys the person on it; events without an email are not sent), with first and last name and the visitor IP for geo. Attribute types follow Ortto’s typed IDs: text as str:cm:, money and decimals as int x1000 (int::v, int:cm:price), quantities as whole numbers. Create each act:cm: activity and its attributes in Ortto first.

An identified purchase (preset ecommerce) is delivered as:

POST https://api.eu.ap3api.com/v1/activities/create

{
  "activities": [
    {
      "activity_id": "act:cm:order-completed",
      "attributes": {
        "int::v": 439990,
        "str:cm:coupon": "SUMMER",
        "str:cm:currency": "GBP",
        "str:cm:order-id": "T-1001"
      },
      "fields": {
        "str::email": "jane.doe@example.com",
        "str::first": "Jane",
        "str::last": "Doe"
      },
      "location": {
        "source_ip": "203.0.113.7"
      }
    }
  ],
  "merge_by": [
    "str::email"
  ]
}

Testing

1. Send a test event from a page running Datafly.js (or use the management UI Event Debugger).
2. In Ortto, open People, find the person by email, and confirm the activity appears on their Activity timeline.
3. Confirm the activity attributes (order ID, value, currency) are populated as expected.
4. A successful call returns 200. A 400 usually means an unknown activity_id or a missing required field; 401/403 indicate a bad or under-scoped key, or the wrong region host.

Troubleshooting

• 401 / 403 — the API key is invalid, lacks activity write access, or you selected the wrong region host. Verify the key in Settings → API keys and confirm the host matches your instance region.
• 400 unknown activity — the activity_id in your event mapping does not exist in Ortto. Create the activity definition first, then copy its act:cm:<slug> ID into the mapping.
• Person not matched — confirm the email trait is set before the event fires and that merge_by is str::email. Without a match key, Ortto cannot attach the activity to a person.
• Activity missing despite a 200 — Ortto limits activities to 50 per activity per contact per 24 hours. High-frequency events (such as page views) on a single contact can hit this cap; map noisy events sparingly.
• Wrong currency amount — int::v expects an integer in cents. Make sure your value mapping multiplies by 100.