CONFIDENTIAL NOTICE. The information contained in this document is strictly confidentialand contains proprietary information. It may only be used by the intended parties and issubject to the terms of any other confidentiality or nondisclosure agreement between parties.
\nFanPass lets you push your own data into FanReach so it can power personalization and targeting.
\nTwo things you can push:
\nImported Segments — lists of user IDs that FanReach uses to target content, push notifications, and campaigns. Send a list inline or upload a file for larger imports.
\nUser Model Attributes — key-value data sent via the userProperties field that updates attributes on an individual user's record. There are two distinct types:
Platform User Properties (user_properties.\\*) — a pre-defined set of attributes (e.g. user_properties.sth, user_properties.ticketing_plans) built into the FanReach User Model. These feed personalization rules and are automatically synced to GA4, attaching to every analytics event for enhanced reporting. → View full list of Platform User Properties
Custom Attributes (custom.\\*) — attributes you define yourself (e.g. custom.loyalty_tier). These must be registered in the FanReach Portal before use. They power personalization and targeting but are not synced to GA4.
The two segment-creation requests target the same POST /api/v1/segments endpoint — the API selects file mode when the request is sent as multipart/form-data with a file part, and JSON mode when a JSON body is sent.
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.
\nTo get started:
\n1. Import this collection into your postman workspace:
\nIn the top right bar of this webpage, click on the Run in Postman.
\nSelect the Workspace you'd like to import this collection into.
\n2. Select the Collection and Go to Variables:
\nIn the sidebar, click on the FanPass API collection.
\nSelect the Variables tab.
\n3. Set Your API Token:
\nYou will see a variable named api_access_token.
In the Current Value column for that variable, paste your JWT Token.
\nThis 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\nSecurity 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.
POST /api/v1/segmentsCreate 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.
\nUsers who renewed season tickets
\nUsers interested in tickets
\nSingle-game ticket holders
\nMerchandise purchasers
\nCRM-based cohorts
\nSponsors and VIPs
\nIf a segment tag does not exist, it will be created.
If a segment tag already exists, its list of userIds will be fully replaced (\"rinse and replace\").
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.
\nRequired. The CSV/XLSX/XLS/ZIP file to import. Click this row's Value cell in the Body → form-data tab and select your file. No file is bundled with this collection.
\n","value":null},{"key":"title","type":"text","value":"User Group 1","description":"Required. A descriptive, friendly name for the segment.
\n"},{"key":"tag","type":"text","value":"userGroup1","description":"Required. Unique alphanumeric identifier used as the primary key. No spaces allowed.
\n"},{"key":"sourceType","type":"text","value":"0","description":"Optional. Source of the user IDs. Defaults to 0 (Ticketing ID).
\n"},{"key":"notes","type":"text","value":"CSV import of User Group 1","description":"Optional. Notes for import logs. Visible in the portal.
\n"},{"key":"dry_run","type":"text","value":"false","description":"Optional. Set to true to validate the file without persisting. Accepts true/1/yes/on.
\n"},{"key":"correlation_id","type":"text","value":"","description":"Optional. Override the auto-generated correlation id for tracing.
\n"}]},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments","description":"POST /api/v1/segments (multipart/form-data)Create or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline userIds array. This is the recommended method for large segments.
This is the same endpoint as Create/Update Segment — the API switches to file mode when the request is sent as multipart/form-data with a file part. The \"rinse and replace\" behavior for an existing tag is identical: if the tag exists, its user list is fully replaced.
File Requirements
\nAllowed extensions: .csv, .xlsx, .xls, .zip. Maximum size: 10 MB.
The first column must be the user ID column.
\nAny additional columns are written to the user's record as User Model Attributes automatically. FanReach resolves each column header using the following order:
\nPlatform User Property — if the column name matches a non-reserved user_properties.\\\\* attribute (e.g. sth, ticketing_plans), it is written there directly. → View full list of Platform User Properties
Custom Attribute — if it doesn't match a Platform User Property, FanReach checks whether the attribute is registered in the FanReach Portal under FanPass. If registered, it is written to custom.\\\\*.
Rejected — if the column name matches neither, the row is rejected and an error is recorded on the segment.
\nAn ID-only file (no extra columns) is valid.
\n\n\nUnknown form fields are ignored. To create a segment from an inline list of IDs instead of a file, use the Create/Update Segment request.
\n
A successful (non-dry_run) response returns a firebase_imported_segment_id and a lookup_key. Use the Get Segment Import Status request to poll the import's progress with that id.
\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","segments"],"host":["fanpass-api.fanreachdata.io"],"query":[],"variable":[]}},"response":[{"id":"16b706c6-8ed8-41b7-b2cd-54c01a303d38","name":"Success Response (200)","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"file","type":"file","description":"Required. The CSV/XLSX/XLS/ZIP file to import. Click this row's Value cell in the Body → form-data tab and select your file. No file is bundled with this collection."},{"key":"title","type":"text","value":"User Group 1","description":"Required. A descriptive, friendly name for the segment."},{"key":"tag","type":"text","value":"userGroup1","description":"Required. Unique alphanumeric identifier used as the primary key. No spaces allowed."},{"key":"sourceType","type":"text","value":"0","description":"Optional. Source of the user IDs. Defaults to 0 (Ticketing ID)."},{"key":"notes","type":"text","value":"CSV import of User Group 1","description":"Optional. Notes for import logs. Visible in the portal."},{"key":"dry_run","type":"text","value":"false","description":"Optional. Set to true to validate the file without persisting. Accepts true/1/yes/on."},{"key":"correlation_id","type":"text","value":"","description":"Optional. Override the auto-generated correlation id for tracing."}]},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments","description":"### Endpoint: `POST /api/v1/segments` (multipart/form-data)\n\n## Create or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline userIds array.\n\nCreate or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline `userIds` array. This is the recommended method for large segments.\n\nThis is the same endpoint as Create/Update Segment — the API switches to file mode when the request is sent as `multipart/form-data` with a `file` part. The \"rinse and replace\" behavior for an existing `tag` is identical: if the `tag` exists, its user list is fully replaced.\n\n**File Requirements**\n\n- Allowed extensions: `.csv`, `.xlsx`, `.xls`, `.zip`. Maximum size: 10 MB.\n \n- The **first column** must be the user ID column.\n \n- Any additional columns are written to the user's record automatically. FanReach resolves each column header using the following order:\n \n 1. **Platform User Property** — if the column name matches a non-reserved `user_properties.\\\\*` attribute (e.g. `sth`, `ticketing_plans`), it is written there directly. → [View full list of Platform User Properties](https://docs.google.com/document/d/1xSwhb64_uVrM37b2K8tcTA3pb_x_nC75PkPVdq8vTGw/edit?tab=t.0#heading=h.ybdyyjajmgj5)\n \n 2. **Custom User Property** — if it doesn't match a Platform User Property, FanReach checks whether the attribute is registered in the FanReach Portal under FanPass. If registered, it is written to `custom.\\\\*`.\n \n 3. **Rejected** — if the column name matches neither, the row is rejected and an error is recorded on the segment.\n \n- An ID-only file (no extra columns) is valid.\n \n\n---\n\n#### Form Fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `file` | File | Yes | The CSV/XLSX/XLS/ZIP file to import. |\n| `title` | Text | Yes | A descriptive, friendly name for the segment. |\n| `tag` | Text | Yes | Unique alphanumeric identifier used as the primary key. No spaces allowed. |\n| `sourceType` | Text | No | Source of the user IDs. Defaults to `0` (Ticketing ID). |\n| `notes` | Text | No | Notes for import logs (e.g., batch ID). Visible in the portal. |\n| `dry_run` | Text | No | Set to `true` to validate the file without persisting. Accepts true/1/yes/on. |\n| `correlation_id` | Text | No | Override the auto-generated correlation id for tracing. |\n\n> Unknown form fields are ignored. To create a segment from an inline list of IDs instead of a file, use the **Create/Update Segment** request. \n \n\n---\n\n#### Tracking Progress\n\nA successful (non-`dry_run`) response returns a `firebase_imported_segment_id` and a `lookup_key`. Use the **Get Segment Import Status** request to poll the import's progress with that id.\n\n> **Setting the file:** In the Body → form-data tab, click the Value cell of the `file` row and choose **Select File**. No file is shipped with this collection."},"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 file queued for import\"\n ],\n \"errors\": [],\n \"firebase_imported_segment_id\": 1042,\n \"lookup_key\": \"userGroup1\"\n}"},{"id":"08c907b1-0931-465c-8a8a-c11f2002b4a6","name":"Error: Missing Fields (400)","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"file","type":"file","description":"Required. The CSV/XLSX/XLS/ZIP file to import. Click this row's Value cell in the Body → form-data tab and select your file. No file is bundled with this collection."},{"key":"title","type":"text","value":"User Group 1","description":"Required. A descriptive, friendly name for the segment."},{"key":"tag","type":"text","value":"userGroup1","description":"Required. Unique alphanumeric identifier used as the primary key. No spaces allowed."},{"key":"sourceType","type":"text","value":"0","description":"Optional. Source of the user IDs. Defaults to 0 (Ticketing ID)."},{"key":"notes","type":"text","value":"CSV import of User Group 1","description":"Optional. Notes for import logs. Visible in the portal."},{"key":"dry_run","type":"text","value":"false","description":"Optional. Set to true to validate the file without persisting. Accepts true/1/yes/on."},{"key":"correlation_id","type":"text","value":"","description":"Optional. Override the auto-generated correlation id for tracing."}]},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments","description":"### Endpoint: `POST /api/v1/segments` (multipart/form-data)\n\n## Create or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline userIds array.\n\nCreate or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline `userIds` array. This is the recommended method for large segments.\n\nThis is the same endpoint as Create/Update Segment — the API switches to file mode when the request is sent as `multipart/form-data` with a `file` part. The \"rinse and replace\" behavior for an existing `tag` is identical: if the `tag` exists, its user list is fully replaced.\n\n**File Requirements**\n\n- Allowed extensions: `.csv`, `.xlsx`, `.xls`, `.zip`. Maximum size: 10 MB.\n \n- The **first column** must be the user ID column.\n \n- Any additional columns are written to the user's record automatically. FanReach resolves each column header using the following order:\n \n 1. **Platform User Property** — if the column name matches a non-reserved `user_properties.\\\\*` attribute (e.g. `sth`, `ticketing_plans`), it is written there directly. → [View full list of Platform User Properties](https://docs.google.com/document/d/1xSwhb64_uVrM37b2K8tcTA3pb_x_nC75PkPVdq8vTGw/edit?tab=t.0#heading=h.ybdyyjajmgj5)\n \n 2. **Custom User Property** — if it doesn't match a Platform User Property, FanReach checks whether the attribute is registered in the FanReach Portal under FanPass. If registered, it is written to `custom.\\\\*`.\n \n 3. **Rejected** — if the column name matches neither, the row is rejected and an error is recorded on the segment.\n \n- An ID-only file (no extra columns) is valid.\n \n\n---\n\n#### Form Fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `file` | File | Yes | The CSV/XLSX/XLS/ZIP file to import. |\n| `title` | Text | Yes | A descriptive, friendly name for the segment. |\n| `tag` | Text | Yes | Unique alphanumeric identifier used as the primary key. No spaces allowed. |\n| `sourceType` | Text | No | Source of the user IDs. Defaults to `0` (Ticketing ID). |\n| `notes` | Text | No | Notes for import logs (e.g., batch ID). Visible in the portal. |\n| `dry_run` | Text | No | Set to `true` to validate the file without persisting. Accepts true/1/yes/on. |\n| `correlation_id` | Text | No | Override the auto-generated correlation id for tracing. |\n\n> Unknown form fields are ignored. To create a segment from an inline list of IDs instead of a file, use the **Create/Update Segment** request. \n \n\n---\n\n#### Tracking Progress\n\nA successful (non-`dry_run`) response returns a `firebase_imported_segment_id` and a `lookup_key`. Use the **Get Segment Import Status** request to poll the import's progress with that id.\n\n> **Setting the file:** In the Body → form-data tab, click the Value cell of the `file` row and choose **Select File**. No file is shipped with this collection."},"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, file\"\n ]\n}"},{"id":"20ec5bcc-58da-4246-a75d-8a9235f4ea87","name":"Error: Unauthorized (401)","originalRequest":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[{"key":"file","type":"file","description":"Required. The CSV/XLSX/XLS/ZIP file to import. Click this row's Value cell in the Body → form-data tab and select your file. No file is bundled with this collection."},{"key":"title","type":"text","value":"User Group 1","description":"Required. A descriptive, friendly name for the segment."},{"key":"tag","type":"text","value":"userGroup1","description":"Required. Unique alphanumeric identifier used as the primary key. No spaces allowed."},{"key":"sourceType","type":"text","value":"0","description":"Optional. Source of the user IDs. Defaults to 0 (Ticketing ID)."},{"key":"notes","type":"text","value":"CSV import of User Group 1","description":"Optional. Notes for import logs. Visible in the portal."},{"key":"dry_run","type":"text","value":"false","description":"Optional. Set to true to validate the file without persisting. Accepts true/1/yes/on."},{"key":"correlation_id","type":"text","value":"","description":"Optional. Override the auto-generated correlation id for tracing."}]},"url":"https://fanpass-api.fanreachdata.io/api/v1/segments","description":"### Endpoint: `POST /api/v1/segments` (multipart/form-data)\n\n## Create or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline userIds array.\n\nCreate or update an Imported Segment by uploading a file (CSV, XLSX, XLS, or ZIP) instead of sending an inline `userIds` array. This is the recommended method for large segments.\n\nThis is the same endpoint as Create/Update Segment — the API switches to file mode when the request is sent as `multipart/form-data` with a `file` part. The \"rinse and replace\" behavior for an existing `tag` is identical: if the `tag` exists, its user list is fully replaced.\n\n**File Requirements**\n\n- Allowed extensions: `.csv`, `.xlsx`, `.xls`, `.zip`. Maximum size: 10 MB.\n \n- The **first column** must be the user ID column.\n \n- Any additional columns are written to the user's record automatically. FanReach resolves each column header using the following order:\n \n 1. **Platform User Property** — if the column name matches a non-reserved `user_properties.\\\\*` attribute (e.g. `sth`, `ticketing_plans`), it is written there directly. → [View full list of Platform User Properties](https://docs.google.com/document/d/1xSwhb64_uVrM37b2K8tcTA3pb_x_nC75PkPVdq8vTGw/edit?tab=t.0#heading=h.ybdyyjajmgj5)\n \n 2. **Custom User Property** — if it doesn't match a Platform User Property, FanReach checks whether the attribute is registered in the FanReach Portal under FanPass. If registered, it is written to `custom.\\\\*`.\n \n 3. **Rejected** — if the column name matches neither, the row is rejected and an error is recorded on the segment.\n \n- An ID-only file (no extra columns) is valid.\n \n\n---\n\n#### Form Fields\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| `file` | File | Yes | The CSV/XLSX/XLS/ZIP file to import. |\n| `title` | Text | Yes | A descriptive, friendly name for the segment. |\n| `tag` | Text | Yes | Unique alphanumeric identifier used as the primary key. No spaces allowed. |\n| `sourceType` | Text | No | Source of the user IDs. Defaults to `0` (Ticketing ID). |\n| `notes` | Text | No | Notes for import logs (e.g., batch ID). Visible in the portal. |\n| `dry_run` | Text | No | Set to `true` to validate the file without persisting. Accepts true/1/yes/on. |\n| `correlation_id` | Text | No | Override the auto-generated correlation id for tracing. |\n\n> Unknown form fields are ignored. To create a segment from an inline list of IDs instead of a file, use the **Create/Update Segment** request. \n \n\n---\n\n#### Tracking Progress\n\nA successful (non-`dry_run`) response returns a `firebase_imported_segment_id` and a `lookup_key`. Use the **Get Segment Import Status** request to poll the import's progress with that id.\n\n> **Setting the file:** In the Body → form-data tab, click the Value cell of the `file` row and choose **Select File**. No file is shipped with this collection."},"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":"506c90ef-945e-4359-a4ce-3740fb79a108"},{"name":"Get Segment Import Status","id":"0600c259-a844-4e79-b5d0-48fa909cfadd","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"firebase_imported_segment_id\": 12345\n}","options":{"raw":{"language":"json"}}},"url":"https://fanpass-api.fanreachdata.io/api/v1/segment_import_status","description":"Setting the file: In the Body → form-data tab, click the Value cell of the
\nfilerow and choose Select File. No file is shipped with this collection.
POST /api/v1/segment_import_statusPoll the progress of a previously submitted Imported Segment — typically one created via a file upload (see Import Segment via CSV upload). Large imports are processed asynchronously, so use this endpoint to check when an import has finished.
\nimport_statusThe import_status object reports progress:
POST /api/v1/update_userThis endpoint allows for real-time enrichment of user records through individual or batch updates of User Model Attributes. These updates enable fine-tuned personalization and audience targeting.
\nUpdate Rules
\nUsers are identified by their unique string-based ID.
\nAttributes are resolved using the following order:
\nPlatform User Property — if the key matches a non-reserved user_properties.\\\\* attribute (e.g. sth, ticketing_plans), it is written there directly. → View full list of Platform User Properties
Custom Attribute — if the key is registered in the FanReach Portal under FanPass, it is written to custom.\\\\*.
Rejected — reserved system properties (e.g. user_id) and unregistered keys are ignored. A warning is returned in the response.
Platform User Properties (user_properties.\\\\*) are synced to GA4 on app open and attached to every subsequent analytics event.
Tags are pushed to the fr_user_tags event stream for audience creation.
userProperties ConstraintsPlatform User Property keys — must match a non-reserved user_properties.\\* attribute. View full list
Custom Attribute keys — must be registered in the FanPass section of the FanReach Portal before use. Unregistered keys will be rejected.
\nKey length — maximum 24 characters (required for GA4 compatibility). Keys exceeding this limit will be ignored.
\nValue length — maximum 36 characters. Values exceeding this limit will be automatically truncated.
\n