> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/integrations/customerio.md).
# Customer.io
Add or update Customer.io profiles with their unique share link and referrer information.
## Sync with Customer.io
**Step 1:** In *Program Editor > 4. Options > Integrations*, open the Customer.io integration card. Enter your Customer.io Site ID and Tracking API key. [Learn how to create and manage Customer.io credentials](https://docs.customer.io/accounts-and-workspaces/managing-credentials/).
**Step 2:** Optionally, enter an App API key if your Customer.io workspace does not use `email` as a profile identifier. The App API key lets GrowSurf find an existing profile by email before it sends an update through the Track API.
Create the App API key in the same Customer.io workspace as the Site ID and Tracking API key. The key must also use the same US or EU region. [Learn about Customer.io App API keys](https://docs.customer.io/integrations/api/app/).
{% hint style="warning" %}
Without an App API key, enable `email` as a profile identifier in Customer.io to prevent duplicate profiles.
{% endhint %}
**Step 3:** Select **Submit**. GrowSurf adds or updates a Customer.io profile when a participant is added, referred, or updated in your referral program.
{% hint style="info" %}
GrowSurf only syncs participants who are added or updated after you connect Customer.io. Connecting the integration does not backfill existing participants. Connect Customer.io before you import participants, or [backfill existing participants](#backfilling-data).
{% endhint %}
{% hint style="info" %}
## How GrowSurf matches profiles
With an App API key, GrowSurf checks Customer.io for an exact email match before each uncached update:
* One matching profile: GrowSurf updates that profile through its Customer.io `cio_id`.
* No matching profile: GrowSurf sends the update by email so Customer.io can create the profile.
* Multiple matching profiles: GrowSurf sends no update. Merge the profiles in Customer.io, then retry the GrowSurf sync.
{% endhint %}
## Examples
[View our Customer.io tutorials](/integrations/customerio/tutorials.md) for examples that you can copy and paste into your email templates.
## Attributes
GrowSurf sends these attributes when a participant syncs. Customer.io adds the attributes to the participant's profile if they do not exist.
| **Attribute Name** | **Attribute Tag** | **Type** | **Description** | **Example** |
| ------------------------------------------ | --------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **`grsf_share_url`** | `{{customer.grsf_share_url}}` | TEXT | The participant's unique referral link | |
| **`grsf_participant_id`** | `{{customer.grsf_participant_id}}` | TEXT | The participant's unique GrowSurf ID | abc123 |
| **`grsf_referral_status`** | `{{customer.grsf_referral_status}}` | TEXT | The referral status of the participant\* | CREDIT\_PENDING |
| **`grsf_participant_first_name`** | `{{customer.grsf_participant_first_name}}` | TEXT | The participant's first name | Bob |
| **`grsf_participant_last_name`** | `{{customer.grsf_participant_last_name}}` | TEXT | The participant's last name | Loblaw |
| **`grsf_referrer_first_name`** | `{{customer.grsf_referrer_first_name}}` | TEXT | The first name of the participant's referrer (if applicable) | Gavin |
| **`grsf_referrer_last_name`** | `{{customer.grsf_referrer_last_name}}` | TEXT | The last name of the participant's referrer (if applicable) | Belson |
| **`grsf_referrer_email`** | `{{customer.grsf_referrer_email}}` | TEXT | The email address of the participant's referrer (if applicable) | |
| **`grsf_total_referral_count`** | `{{customer.grsf_total_referral_count}}` | NUMBER | The participant's all-time referral count | 0 |
| **`grsf_monthly_referral_count`** | `{{customer.grsf_monthly_referral_count}}` | NUMBER | The participant's current month referral count | 19 |
| **`grsf_previous_monthly_referral_count`** | `{{customer.grsf_previous_monthly_referral_count}}` | NUMBER | The participant's previous month referral count | 200 |
| **`grsf_next_milestone`** | `{{customer.grsf_next_milestone}}` | TEXT | The text for the next milestone reward. Only applies to milestone rewards. [See an example](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone). | You are only 2 referrals away from winning a free t-shirt! |
| **`grsf_next_monthly_milestone`** | `{{customer.grsf_next_monthly_milestone}}` | TEXT | The text for the next monthly milestone reward. Only applies to milestone rewards. [See an example](https://docs.growsurf.com/developer-tools/embeddable-elements#embedded-next-milestone). | You are only 2 referrals away from winning a free t-shirt! |
| **`grsf_total_invite_count`** | `{{customer.grsf_total_invite_count}}` | NUMBER | The participant's all-time invite count | 112 |
| **`grsf_total_impression_count`** | `{{customer.grsf_total_impression_count}}` | NUMBER | The participant's all-time impression count | 150 |
`grsf_referral_status` can have one of these values:
* `CREDIT_PENDING`: The participant must trigger a referral before their referrer receives credit.
* `CREDIT_AWARDED`: The participant triggered a referral, and their referrer received credit.
* `CREDIT_EXPIRED`: The participant did not trigger a referral before the referral credit expired.
You can use these attributes in your Customer.io email templates. For example, use `{{customer.grsf_share_url}}` to add each participant's unique referral link.
[Learn how to use profile attributes in Customer.io messages](https://docs.customer.io/messaging/liquid/using-liquid/).
## Backfilling data
To add GrowSurf attributes to Customer.io profiles that existed before you connected the integration:
1. Connect your GrowSurf program to Customer.io.
2. [Export the Customer.io profiles as a CSV file](https://docs.customer.io/messaging/profiles/manage/exporting-users/). Include the `email` attribute.
3. Import the CSV file into your GrowSurf program. GrowSurf then syncs the imported participants and their `grsf_*` attributes to Customer.io.
## Troubleshooting tips
If a participant or attribute is missing in Customer.io:
* Confirm that the participant was added or updated after you connected Customer.io. Otherwise, follow the backfill steps above.
* Confirm that the participant has the same email address in GrowSurf and Customer.io.
* Confirm that your Customer.io workspace [uses `email` as a profile identifier](https://docs.customer.io/journeys/identifying-people/). Otherwise, GrowSurf cannot match an existing profile by email, and Customer.io may create a duplicate.
* If you saved an App API key, confirm that it belongs to the same workspace and region as the Site ID and Tracking API key.
* If GrowSurf reports multiple profiles with the same email, merge them in Customer.io. Then update the participant again to retry the sync.
* If you deleted a matched profile, wait five minutes after the last successful lookup. Then update the participant again so GrowSurf checks Customer.io before it sends the next update.
* Check your GrowSurf activity logs for the Customer.io sync result. GrowSurf automatically retries temporary sync failures.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.growsurf.com/integrations/customerio.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
%202026-09-03%20at%205.09.44%20PM.png?alt=media&token=3cd494a0-27ad-4a1d-ac7d-3bab7399d074)