Funnel users

A funnel user is one person's record in one funnel: who they are, what they answered, where they came from and their subscription status. Subscriptions themselves are listed separately in Subscriptions.

{
  "id": "<funnel-user-id>",
  "userId": "u_123",
  "funnelId": "<funnel-id>",
  "email": "person@example.com",
  "fullName": "Ann Lee",
  "subscriptionStatus": "active",
  "test": false,
  "answers": { "goal": "sleep-better" },
  "metadata": { "plan": "yearly" },
  "attribution": {
    "firstTouch": { "utm_source": "facebook", "utm_campaign": "spring" },
    "lastTouch": { "utm_source": "tiktok" },
    "lastNonOrganicTouch": { "utm_source": "tiktok" }
  },
  "geo": { "country": "US", "city": "Austin" },
  "createdAt": "2026-10-01T10:00:00+00:00",
  "updatedAt": "2026-10-05T12:00:00.123456+00:00",
  "lastSeenAt": "2026-10-05T12:00:00+00:00"
}

Field	Meaning
id	The funnel user record ID.
userId	The funnelsgrove user ID your app saves after sign-in.
subscriptionStatus	The latest known subscription status, or null.
test	true for users created in test mode.
answers	The user's quiz answers, keyed by question.
metadata	Custom metadata your funnel stored on the user.
attribution	First, last and last non-organic touch, with the UTM parameters the funnel recorded.

To keep a copy of a project's users up to date, follow the sync guide.

Project secret keys

Requests with a project secret key still return the earlier, larger response (with payments and events). New integrations use API keys and the format on this page.

Get funnel user

Looks one user up by funnelsgrove user_id, by email, or by funnelUserId.

Scope: funnel_users:read

Request

GET /funnel-users?projectId=<project-id>&funnelId=<funnel-id>&user_id=<user-id>

Parameters

Query	Required	Purpose
projectId	Yes	The project that owns the funnel.
funnelId	Unless funnelUserId is sent	The funnel to search.
user_id	One of the three	The funnelsgrove user ID returned to your app.
email	One of the three	The user's email address.
funnelUserId	One of the three	The funnel user id. Needs no funnelId.

Example

curl "https://sdk-api.funnelsgrove.com/integration/v1/funnel-users?projectId=<project-id>&funnelId=<funnel-id>&user_id=<user-id>" \
  -H "Authorization: Bearer <api-key>"

Response

{ "user": { "id": "<funnel-user-id>", "userId": "u_123", "…": "…" } }

Errors

Status	Meaning
400	No lookup key, or funnelId is missing.
404	No funnel user matches, or the funnel belongs to another project.

List funnel users

Pages through the project's users in updatedAt order, oldest first.

Scope: funnel_users:read

Request

GET /funnel-users/list?projectId=<project-id>&updatedSince=<iso-timestamp>

Parameters

Query	Required	Purpose
projectId	Yes	The project to list.
funnelId	No	Limit the list to one funnel.
updatedSince	No	ISO 8601 timestamp. Returns users whose updatedAt is at or after it.
cursorUpdatedAt, cursorId	No	The nextCursor values of the previous page. Both are required together.
limit	No	Page size, up to 100 (default 50).

Timestamps must be canonical ISO 8601 (2026-10-20T00:00:00Z or …T00:00:00.123456+00:00). Encode + as %2B.

Example

curl "https://sdk-api.funnelsgrove.com/integration/v1/funnel-users/list?projectId=<project-id>&updatedSince=2026-10-20T00:00:00Z&limit=100" \
  -H "Authorization: Bearer <api-key>"

Response

{
  "project": { "id": "<project-id>" },
  "items": [{ "id": "<funnel-user-id>", "userId": "u_123", "updatedAt": "…", "…": "…" }],
  "nextCursor": { "updatedAt": "2026-10-20T10:00:00.123456+00:00", "id": "<funnel-user-id>" }
}

• nextCursor is null on the last page.
• A user's updatedAt changes when their profile, answers, email or login change, and after every payment, refund and subscription change. Chargebacks do not change it. Background maintenance can also change it, so expect some users to repeat.

Errors

Status	Meaning
400	A timestamp is not ISO 8601, or cursorUpdatedAt was sent without a UUID cursorId.
404	funnelId does not belong to the project.