Prerequisites

• You must have Company or App Administrator permissions in Recurly Engage.
• For CSV ingest: access to your Engage S3 bucket or a CSV export source.
• For real‑time ingest via the Ingest API: your App ID and API Key (Settings > Application > API Key).

Limitations

• For third‑party connector activation, ensure required ID columns are present.
• CSV uploads to S3 are ingested within a few hours — for real‑time updates, use the Ingest API.

Definition

Key benefits

Key details

• CSV format: First column must be user_id, additional columns become traits.
• Trait types: Number, string, boolean, date with corresponding display options (slider, multi‑select, date range).
• Push endpoints: Import device tokens via CSV or Device Registration API.
• 3rd‑party requirements: Specific ID or email columns needed for connectors (e.g., stripe_id, email_address).

You can import additional user traits into Recurly Engage to give you greater ability to target users based on characteristics beyond site/app usage. Typical examples are lifetime value, customer satisfaction score, subscription start date, renewal date etc. User traits can be added via a CSV file. This file will be stored, encrypted, on a secured S3 bucket and will be ingested within a few hours of uploading. Each column will be mapped into a Recurly Engage user trait.

You can also export your CSV data from Looker.

Choosing an ingest method

Recurly Engage supports three ways to get custom trait data in. Pick the one that matches how fresh your data needs to be and where it lives.

Method 1 — CSV upload to S3 (batch)

You can import user traits into Recurly Engage to target users on characteristics beyond site or app usage. Typical examples are lifetime value, customer satisfaction score, subscription start date, and renewal date. User traits can be added via a CSV file. This file is stored, encrypted, on a secured S3 bucket and is ingested within a few hours of uploading. Each column is mapped into a Recurly Engage user trait.

You can also export your CSV data from Looker.

One-off uploads

If you need to load a small, one-time batch of trait data — for example, an exclusion list or a short-term partner list — you can upload a CSV directly in Pulse instead of dropping a file to your S3 bucket:

This method mimics the same processing your S3 uploads go through, just triggered manually rather than automatically. It's best suited for small, one-time uploads — for ongoing or recurring trait syncs, use the S3 method above.

Formatting the CSV file

Here is an example of what your CSV file should look like. The first column must beuser_id, all other columns can be utilized to specify user traits. There are no limits on columns but please keep in mind this can significantly impact load and sync times.

user_id,ltv,channel,signup_date,nps,plan_type,payment_failed
789129,150,adwords,2011-08-12,8,monthly,false
322321,0,blog,2014-09-18,7,trial,false
900194,100,homepage,2018-04-01,9,annual,true

• Trait key casing is case-sensitive. If you change the casing of a column header between uploads (for example, LTV vs. ltv), Engage treats it as a brand-new trait rather than an update to the existing one — this creates duplicate traits and inconsistent data. Keep column header casing identical across every file you upload.
• Trait keys must use underscores, not spaces. A column header containing a space (e.g. signup date) will not be processed. Use signup_date instead.
• Only include traits you actually plan to use for segmentation. Every additional column increases file size and processing time. If you upload traits you don't intend to use, you'll still need to configure each one (see "Customizing user traits" above) before they're usable.
• Do not include personally identifiable information (PII) in trait columns.

Required columns for third party connectors

• Salesforce: salesforce_id (the id of the Salesforce contact) OR email_address
• SendGrid: email_address
• Stripe: stripe_id (the id of the Stripe customer) OR email_address
• Zendesk: zendesk_id (the id of the Zendesk user) OR email_address

Push notifications

To activate push notifications, the following columns are required:

1. Id: the id of the device (aka endpoint)
2. ChannelType: the push channel of this endpoint. Allowed values: FCM, ADM, APNS
3. Address: The device token
4. User.UserId: the id of the user. This should be the same id that Recurly Engage uses

This CSV can be used as a one‑time initial load of endpoint information. To keep this information updated, you may:

1. Upload an updated CSV periodically into your S3 bucket from Recurly Engage OR
2. Call the Device Registration API with the device token from your client application

Upload the file to AWS

After creating your CSV file you will need to upload it to your secure area on Amazon S3. In this step we will retrieve the credentials to allow you to upload the file.

Method 2 — Partner integrations

If your data already lives in a supported tool — such as Segment, Stripe, Braze, or Salesforce — you can sync traits by connecting that tool directly, without preparing and uploading a CSV yourself. Set the integration up in Pulse (Engage Backend) and trait updates propagate into Engage on their own. Latency depends on the partner; for example, Segment traits typically appear within minutes. See CRM integrations for the full list and setup steps.

Method 3 — Ingest API (real time)

When your data lives in your own backend or internal database — or you simply need updates faster than the batch cycle allows — call the Ingest API directly. There's no S3 upload and no batch wait; traits are available as soon as the call succeeds.

• Endpoint: POST https://conduit.redfast.com/ingest/property
• Authentication: Basic Auth with your Application ID and API Key. Depending on your client, the API Key may be passed as a query-string parameter. Find your API Key at Settings > Application > API Key.

Payload:

{
  "id": "123-456-789-012",
  "user_id": "test-user-001",
  "properties": {
    "first_name": "Jane",
    "plan": "premium"
  }
}

Example response

{
  "success": true
}

Each key in properties maps to a Recurly Engage user trait. As with CSV ingest, you'll configure the type and display for each new trait before using it in a segment (see Customizing user traits).

Error responses

A few behaviors worth knowing:

• You don't need to include user_id inside the properties object — it's automatically attached to the trait set from the user ID you provide in the request.
• Sending the exact same trait values for the same user repeatedly is treated as a no-op — it won't cause an error, but it also won't re-trigger any downstream processing. Only send a trait update when a value has actually changed.
• Depending on your account's configuration, certain trait keys may be filtered out automatically. If a trait you're sending isn't showing up, contact Recurly support to check your configuration.
• As with other ingest methods, this is processed asynchronously — a successful response confirms the request was accepted, not that it's finished processing.

Method 4 — Live ingest via Custom JS Snippet

If your trait data already lives on the client — in cookies, localStorage, a data layer, or reachable through a call to your own backend — you can push it into Recurly Engage on every page load by implementing a fetchUserTraits() function in your Custom JS Snippet. This works alongside the fetchUserId() and fetchAnonUserId() functions described in Custom JS snippet.

fetchUserTraits() returns an object whose keys map to Recurly Engage user traits — the same shape as the properties object in the Ingest API payload.

static fetchUserTraits() {
  const user = JSON.parse(localStorage.getItem("user_object"));
  return {
    is_registered: !!user.token,
    member_since: user.registrationDate,
    accepted_tos: localStorage.getItem("tos_acceptance_date")
  };
}

Customizing user traits

After a trait is ingested — whether by CSV, a partner integration, or the Ingest API — you'll need to configure it before you can use it in your segments.

This may seem intimidating at first but let's take a look at the original CSV to see what the values should be:

user_id,ltv,channel,signup_date,nps,plan_type,payment_failed
789129,150,adwords,2011-08-12,8,monthly,false
322321,0,blog,2014-09-18,7,trial,false
900194,100,homepage,2018-04-01,9,annual,true

• ltv – number
• channel – string
• signup_date – date
• nps – number
• plan_type – string
• payment_failed – boolean

Now that we know the types, selecting the display is easy. Here are some guidelines for display options:

• numbers – slider (unless it refers to an ID such as zendesk_id, then multi‑select)
• string – multi‑select
• boolean – multi‑select
• date – date_range

Common issues & how to resolve them