{"info":{"_postman_id":"eae8d08b-d3d0-453e-ac42-f225a542573d","name":"FanPass API","description":"

CONFIDENTIAL NOTICE. The information contained in this document is strictly confidential
and contains proprietary information. It may only be used by the intended parties and is
subject to the terms of any other confidentiality or nondisclosure agreement between parties.

Overview

FanPass is a secure, flexible API that enables clients to manage and enrich user data for personalized engagement. It supports two primary functions:

Segment Management: Import and update lists of users to create dynamic \"Imported Segments\" that can drive targeting across Push Notifications, In-App Messages, Marketing Card Campaigns, and Personalization Rules.
\n
User Attribute Enrichment: Update individual user records with key-value pairs for both platform and custom user attributes. These updates feed directly into the personalization engine and reporting tools, such as GA4 User Properties.
\n

This collection helps teams activate their customer data with real-time updates and high precision, enabling richer, more relevant user experiences across your digital ecosystem.

Getting Started with this Postman Collection

This collection can be imported into any Postman workspace. It allows you to explore the FanPass API, validate your integration, and reproduce issues for support. It uses variables to manage the API host and your authentication token.

To get started:

1. Import this collection into your postman workspace:

In the top right bar of this webpage, click on the Run in Postman.
\n
Select the Workspace you'd like to import this collection into.
\n

2. Select the Collection and Go to Variables:

In the sidebar, click on the FanPass API collection.
\n
Select the Variables tab.
\n

3. Set Your API Token:

You will see a variable named api_access_token.
\n
In the Current Value column for that variable, paste your JWT Token.
\n
This JWT Token is generated in the Fanreach Portal. It is unique to your user for auditing purposes. Ensure your JWT remains secure and do not share it externally. If your token is compromised, contact FanReach support immediately to issue a new one.
\n

\n
Security Best Practice: Using the Current Value field ensures your secret token remains on your local machine and will not be synced with Postman's servers or exposed if you share the collection.
\n

The domain variable is already set to the production host. Once your token is set, you can run any request.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Overview","slug":"overview"},{"content":"Getting Started with this Postman Collection","slug":"getting-started-with-this-postman-collection"}],"owner":"1065403","collectionId":"eae8d08b-d3d0-453e-ac42-f225a542573d","publishedId":"2sB2x6kC5M","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2025-06-12T18:11:07.000Z"},"item":[{"name":"Create/Update Segment","id":"d1a159af-2be7-4f9e-b7c6-07a3391fe83c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"User Group 1\",\n \"tag\": \"userGroup1\",\n \"sourceType\": 0,\n \"userIds\": [\"12345\",\"54321\",\"56435\"],\n \"notes\": \"Refresh of User Group 1\"\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments","description":"

Endpoint: `POST /api/v1/segments`

Create or update Imported Segments by uploading lists of user IDs. These segments are typically based on behavioral or transactional data and are used to power campaign targeting and personalization.

Common Segment Examples

Users who renewed season tickets
\n
Users interested in tickets
\n
Single-game ticket holders
\n
Merchandise purchasers
\n
CRM-based cohorts
\n
Sponsors and VIPs
\n

Important Notes

If a segment tag does not exist, it will be created.
\n
If a segment tag already exists, its list of userIds will be fully replaced (\"rinse and replace\").
\n
Imported Segments are immediately available for the Personalization Engine. It may take up to 12 hours for changes to reflect in Push Notifications and In-App Messages.
\n

Request Body Parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`title`	`String`	Yes	A descriptive, friendly name for the segment.
`tag`	`String`	Yes	Unique alphanumeric identifier used as the primary key. No spaces allowed.
`userIds`	`Array`	Yes	An array of user identifiers (e.g., Ticketing IDs). The array must not be empty.
`sourceType`	`Integer`	No	Integer indicating the source of the user IDs. Defaults to `0`. `0` - Ticketing ID `1` - Push Notification ID (coming soon) `2` - Loyalty ID (coming soon) `3` - Ad ID (coming soon) `4` - Subscriber ID (coming soon)
`notes`	`String`	No	Optional string for import logs (e.g., batch ID). This is visible in the portal.

","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"eae8d08b-d3d0-453e-ac42-f225a542573d","id":"eae8d08b-d3d0-453e-ac42-f225a542573d","name":"FanPass API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v1","segments"],"host":["fanpass-api.fanreachdata.io"],"query":[],"variable":[]}},"response":[{"id":"0f71b1e6-77d0-4d59-87a6-9e5531ac5896","name":"Success Response (200)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"User Group 1\",\n \"tag\": \"userGroup1\",\n \"sourceType\": 0,\n \"userIds\": [\"12345\",\"54321\",\"56435\"],\n \"notes\": \"Refresh of User Group 1\"\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"correlationId\": \"95e0bd4c-35e4-4cd4-9e4c-46e06f7b58a1\",\n \"messages\": [\n \"Segment User Group 1 queued 3 for import\"\n ],\n \"errors\": []\n}"},{"id":"75b0f565-47d4-48fc-95e6-1a17c5ca3170","name":"Error: Missing Fields (400)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"notes\": \"Trying to create a segment with missing fields.\"\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 400,\n \"correlationId\": \"b2c3d4e5-f6a7-8901-2345-67890abcdef1\",\n \"messages\": [],\n \"errors\": [\n \"Missing required fields: title, tag, userIds\"\n ]\n}"},{"id":"69b0f380-c8ed-4d89-bce1-43e4aa26a50f","name":"Error: Unauthorized (401)","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer an-invalid-token"}],"body":{"mode":"raw","raw":"{\n \"title\": \"User Group 1\",\n \"tag\": \"userGroup1\",\n \"sourceType\": 0,\n \"userIds\": [\"12345\",\"54321\",\"56435\"],\n \"notes\": \"Refresh of User Group 1\"\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 401,\n \"correlationId\": \"d2e1f3a0-c4b5-6789-0123-456789abcdef\",\n \"messages\": [],\n \"errors\": [\n \"The API access token is missing or invalid. Please verify that you are using the correct FanPass API token, which is available in the Fanreach Portal.\"\n ]\n}"}],"_postman_id":"d1a159af-2be7-4f9e-b7c6-07a3391fe83c"},{"name":"Update User Properties","id":"6888ce1a-4f97-4a28-8026-e36f2d610b0e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userIds\": [\"12345\"],\n \"userProperties\": {\n \"example_property_1\": \"example_value_1\",\n \"example_property_2\": \"example_value_2\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/update_user","description":"

Endpoint: `POST /api/v1/update_user`

This endpoint allows for real-time enrichment of user records through individual or batch updates of user properties. These updates enable fine-tuned personalization and audience targeting.

Update Rules

Users are identified by their unique string-based ID.
\n
Custom property keys must be registered in the FanReach Portal as custom attributes before use.
\n
Reserved properties (e.g., user_id) are not allowed and will be ignored. A warning will be returned in the response.
\n
All valid custom property updates are appended to the GA4 User Property model.
\n
GA4 propagation may take 4–8 hours to reflect changes across targeting tools.
\n
Tags are pushed to the fr_user_tags event stream for audience creation.
\n

Request Body Fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`userIds`	`Array`	Yes	An array of user IDs to update.
`userProperties`	`Object`	Yes	A key-value object of properties to update for the specified users. See notes for constraints.

`userProperties` Constraints

Reserved Keys: Please visit the Fanpass section of the Fanreach portal to view reserved user attributes/properties.
\n
Custom Keys: Please visit the Fanpass section of the Fanreach portal to add custom user attributes/properties.
\n
Key Length: Custom property keys have a maximum length. Keys exceeding this limit will be ignored.
\n
Value Length: Property values have a maximum length of 36 characters. Values exceeding this limit will be automatically truncated.
\n

\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"eae8d08b-d3d0-453e-ac42-f225a542573d","id":"eae8d08b-d3d0-453e-ac42-f225a542573d","name":"FanPass API","type":"collection"}},"urlObject":{"protocol":"https","path":["api","v1","update_user"],"host":["fanpass-api.fanreachdata.io"],"query":[],"variable":[]}},"response":[{"id":"4bfd8f67-119a-45e3-899c-941fda5ed52f","name":"Success Response (200)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userIds\": [\"12345\"],\n \"userProperties\": {\n \"example_property_1\": \"example_value_1\",\n \"example_property_2\": \"example_value_2\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/update_user"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"correlationId\": \"d8c4e0a2-3b1f-4d9a-8c1e-2a3b4c5d6e7f\",\n \"messages\": [\n \"Successfully updated user properties for 1 users\"\n ],\n \"errors\": []\n}"},{"id":"8098543f-1af9-40d1-88f9-59d5ea021897","name":"Error: Missing Fields (400)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"userProperties\": {}\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/update_user"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 400,\n \"correlationId\": \"c7b3d9f1-2a0e-4c89-7b0d-1a2b3c4d5e6f\",\n \"messages\": [],\n \"errors\": [\n \"Missing required fields: userIds, userProperties\"\n ]\n}"},{"id":"7dcdf6e6-5a28-4aa4-b577-5f6f6ce82c1b","name":"Error: Unauthorized (401)","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer an-invalid-token"}],"body":{"mode":"raw","raw":"{\n \"userIds\": [\"12345\"],\n \"userProperties\": {\n \"example_property_1\": \"example_value_1\",\n \"example_property_2\": \"example_value_2\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/update_user"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 401,\n \"correlationId\": \"e3f2g4b1-d5c6-7890-1234-567890abcdef\",\n \"messages\": [],\n \"errors\": [\n \"The API access token is missing or invalid. Please verify that you are using the correct FanPass API token, which is available in the Fanreach Portal.\"\n ]\n}"}],"_postman_id":"6888ce1a-4f97-4a28-8026-e36f2d610b0e"}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"f7c1081a-c8c5-4022-afb5-bde4b77fb6d7","type":"text/javascript","requests":{},"exec":[""]}},{"listen":"test","script":{"id":"e2a12c35-ae83-4e76-84c8-4023e8bd1d34","type":"text/javascript","requests":{},"exec":[""]}}],"variable":[{"key":"domain","value":"fanpass-api.fanreachdata.io"},{"key":"api_access_token","value":""}]}