> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fanfeed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a user

> Create a FanFeed user when your user opts in, and store the id.

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

### The flow

```
  1. User taps "Sync Now" in your app
  2. You show terms and conditions; user agrees
  3. Your backend calls POST /users with their email
  4. FanFeed returns a user_id
  5. You store that user_id against your user record
  6. 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

```http theme={null}
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

```json theme={null}
{
  "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.