From 00aa99a4cd78b93030533499ff06b05fabd33519 Mon Sep 17 00:00:00 2001
From: Grey Moore <grey@controlshiftlabs.com>
Date: Wed, 31 Dec 2025 09:24:51 -0500
Subject: [PATCH 1/2] docs for new "user lookup by facebook_id" endpoint

---
 .../includes/authenticated_api/_users.md.erb  | 45 +++++++++++++++++++
 source/index.html.md                          |  1 +
 2 files changed, 46 insertions(+)
 create mode 100644 source/includes/authenticated_api/_users.md.erb

diff --git a/source/includes/authenticated_api/_users.md.erb b/source/includes/authenticated_api/_users.md.erb
new file mode 100644
index 00000000000..c4cb3361d35
--- /dev/null
+++ b/source/includes/authenticated_api/_users.md.erb
@@ -0,0 +1,45 @@
+## User Accounts
+
+A user account is created when someone signs up with an email address and password on the web, or when they log in via Google or Facebook.
+
+User accounts are unique by email address. Each member has either 0 or 1 user account.
+
+<div></div>
+
+### Lookup by Facebook ID
+
+> GET response body for Lookup
+
+```json
+{
+  "user": {
+    "id": 123,
+    "email": "foo@bar.com",
+    "created_at": "2015-06-01T15:37:47Z",
+    "updated_at": "2017-07-01T11:23:45Z",
+    "member_id": 345,
+    "active_directory_id": null,
+    "facebook_id": "12345678901234",
+    "google_id": null,
+    "last_sign_in_at": "2018-07-02T12:23:12Z",
+    "current_sign_in_at": "2023-03-01T09:03:17Z",
+    "first_name": "Jane",
+    "last_name": "Doe",
+    "phone_number": "555-555-5555",
+    "postcode": "12345",
+    "country": "US",
+    "locale": "en-US",
+    "activated": true,
+    "locked": false
+  }
+}
+```
+
+Find a user account by Facebook UID.
+Note that a user account will only have a Facebook ID if the user has used the "Log in with Facebook" feature.
+This does not necessarily mean that the account was _created_ via "Log in with Facebook";
+it is possible to use Facebook to log in to an existing user account.
+
+`GET /api/v1/users/lookup?facebook_id=12345678901234`
+
+<div></div>
diff --git a/source/index.html.md b/source/index.html.md
index 93c75e1afd3..914d6460b90 100644
--- a/source/index.html.md
+++ b/source/index.html.md
@@ -25,6 +25,7 @@ includes:
   - authenticated_api/email_opt_in_types
   - authenticated_api/consent_content_versions
   - authenticated_api/members.md.erb
+  - authenticated_api/users.md.erb
   - authenticated_api/petitions.md.erb
   - authenticated_api/signatures.md.erb
   - authenticated_api/efforts.md.erb

From a29c90970b9374e6febec685ca1d7c61201f4233 Mon Sep 17 00:00:00 2001
From: Grey Moore <grey@controlshiftlabs.com>
Date: Fri, 2 Jan 2026 15:00:53 -0500
Subject: [PATCH 2/2] clarify terms for Facebook ID

---
 source/includes/authenticated_api/_users.md.erb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/includes/authenticated_api/_users.md.erb b/source/includes/authenticated_api/_users.md.erb
index c4cb3361d35..cbd38d4c902 100644
--- a/source/includes/authenticated_api/_users.md.erb
+++ b/source/includes/authenticated_api/_users.md.erb
@@ -35,8 +35,8 @@ User accounts are unique by email address. Each member has either 0 or 1 user ac
 }
 ```
 
-Find a user account by Facebook UID.
-Note that a user account will only have a Facebook ID if the user has used the "Log in with Facebook" feature.
+Find a user account by Facebook User ID.
+Note that a user account will only have a `facebook_id` if the user has used the "Log in with Facebook" feature.
 This does not necessarily mean that the account was _created_ via "Log in with Facebook";
 it is possible to use Facebook to log in to an existing user account.