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.

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

Ortto creates or matches the person from the fields listed in merge_by:

• Email (str::email) is the primary match key.
• Phone (phone::number, normalised to E.164) can be used as a fallback.

Email and phone are sent in plaintext: Ortto is a first-party customer-data platform and stores these directly, so no hashing is applied. Marketing consent (from your CMP, via Signal’s canonical consent category) is mapped to Ortto’s email-permission flag bol::p so opt-out states are respected on the person record. The visitor IP is sent as location.source_ip for Ortto’s geo enrichment.

Event Mapping

A Datafly.js purchase event:

datafly.track("Order Completed", {
  order_id: "ORD-4821",
  revenue: 153.00,
  currency: "GBP",
  coupon: "SUMMER10"
});

with identity traits already set:

datafly.identify({
  email: "billie.holiday@email.com",
  first_name: "Billie",
  last_name: "Holiday"
});

is delivered to Ortto as:

{
  "activities": [
    {
      "activity_id": "act:cm:order-completed",
      "fields": {
        "str::email": "billie.holiday@email.com",
        "str::first": "Billie",
        "str::last": "Holiday",
        "bol::p": true
      },
      "attributes": {
        "str:cm:order-id": "ORD-4821",
        "int::v": 15300,
        "str:cm:currency": "GBP",
        "str:cm:coupon": "SUMMER10"
      },
      "location": { "source_ip": "203.0.113.7" }
    }
  ],
  "merge_by": ["str::email"],
  "merge_strategy": 2
}

Note that monetary value is sent to Ortto’s int::v field in cents (153.00 becomes 15300).

Event names follow Signal’s GA4-style snake_case convention (page, Product Viewed, Order Completed, Signed Up). Events not present in your mapping are dropped by default.

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.