diff --git a/api-reference.md b/api-reference.md
index 40c1b94..f8ba006 100644
--- a/api-reference.md
+++ b/api-reference.md
@@ -82,7 +82,7 @@ Events may also be created without documents, in which case the `document` and `
 | `document` | `Document`? | no | Associated `Document`, if it exists. |
 | `user_id` | integer | yes | (Internal) UID of the user which triggered this event. |
 | `user` | `User` | no | `User` which triggered this event. |
-| `user_name` | string | yes | Name of the user when they triggered this event. |
+| `user_name` | string? | yes | Name of the user when they triggered this event. |
 | `occurred_at` | timestamp | yes | When this event originally occurred. Will typically be earlier than `created_at` |
 | `created_at` | timestamp | no | When this event was created. Automatically set on creation. |
 | `event_type` | string in `EventType` | yes | Type of the event. Must be one of the event types. |
@@ -177,12 +177,22 @@ Represents a twitch user.
 | field        | type      | required | description                                                             |
 | ------------ | --------- | -------- | ----------------------------------------------------------------------- |
 | `user_id`    | integer   | -        | Internal UID of this user. (NOT the twitch userid)                      |
-| `twitch_id`  | string    | yes      | Twitch user-id for this user. Stored as a string.                       |
-| `name`       | string    | yes      | Twitch name for this user. May not be up to date.                       |
+| `twitch_id`  | string?    | yes      | Twitch user-id for this user. Stored as a string.                       |
+| `name`       | string?    | yes      | Twitch name for this user. May not be up to date.                       |
 | `created_at` | timestamp | no       | When this user was created (internally). Automatically set on creation. |
 
 // The name is stored mainly for easy visual reference/convenience when debugging, and should not be relied on.
 
+Note that the `twitch_id` and `name` parameters are best-effort and there are some rare cases where they are unreliable:
+- If a user linked their twitch account to Discord, and then unlinked the twitch account or deleted it, then `twitch_id` and `name` may be `null`.
+- If a user linked *multiple* twitch accounts, then the returned `twitch_id` and `name` will only be for one account.
+    - In this rare case, filter parameters will still fetch the correct user. This may lead to technically unexpected behaviour, for example:
+        - Assume a user with `user_id` `10` has linked twitch account `1` and later twitch account `2`.
+        - Then both `GET /users?twitch_id=2` and `GET /users?twitch_id=1` will return `{"user_id": 10, "twitch_id": 1}`.
+- Due to the general ephemeral nature of names, it is not recommended to rely on the `name` field in any way. It is included mainly for ease of debugging and reference.
+
+- [ ] Currently there is no way of retrieving *all* the twitch accounts associated to a user. Is this needed?
+
 
 - `POST` `/users`
     - Create and return a `User`