Creating a user

Call this once per user, when they opt in, not on every app launch.

The flow

User taps "Sync Now" in your app
You show terms and conditions; user agrees
Your backend calls POST /users with their email
FanFeed returns a user_id
You store that user_id against your user record
Every later call uses it

Do not call this endpoint again for a user you have already created. The user_id is the handle, and losing it means losing the link to their synced history. Persist it durably before you start syncing.

Request

POST /v1/users
X-PARTNER-API-KEY: <your partner key>
Content-Type: application/json

{
  "email": "fan@example.com",
  "partner_user_id": "partner_user_12345",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "+12125551234",
  "address": {
    "city": "New York",
    "region": "NY",
    "postal_code": "10001",
    "country": "US"
  }
}

Field	Required	Notes
`email`	✔	The only required field.
`partner_user_id`	—	Your own id for this user, stored against the FanFeed profile. Strongly recommended; it is what lets both sides reconcile if the mapping is ever lost.
`first_name`	—	User’s first name.
`last_name`	—	User’s last name.
`phone_number`	—	Stored when it is not already in use by another profile, and silently ignored when it is. Never causes this call to fail.
`address`	—	Stored on the profile. Not used for matching; matching is driven entirely by photo coordinates. Safe to omit.

Send only what you already hold. None of the optional fields change what FanFeed can match; they exist so a profile is recognizable to the person it belongs to.

Response

{
  "user_id": "8f14e45f-ceea-467a-9a1e-2b4d9c3f0a11",
  "existing": false,
  "created_at": "2026-08-25T18:31:07Z"
}

existing is true when FanFeed returned an existing profile for that email instead of creating a new one. Both cases return 201. Calling this endpoint twice for the same email returns the same profile rather than creating a second one, so a retry after a timeout is safe. Idempotency is scoped to your partner key: the same email under a different FanFeed partner is a different profile, and neither can see the other.

Getting started

Integration

Reference

The flow

Request

Response

​The flow

​Request

​Response

The flow

Request

Response