Skip to content

Commit 11bef38

Browse files
AmanGIT07AmanGIT07
authored
doc: add documentation of prospects (#915)
* doc: add documentation of prospects * doc: add prospects to sidebar * doc: refactor overview statements * fix: typo in code samples
1 parent 6bf0e32 commit 11bef38

File tree

2 files changed

+248
-0
lines changed

2 files changed

+248
-0
lines changed

‎docs/docs/prospects/introduction.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
# Introduction
2+
3+
## Overview
4+
Prospects in Frontier stores and manage subscription preferences for various activities like newsletters, blog updates, and marketing communications. Unlike user preferences which are tied to registered accounts (registered account means record is present in users table), Prospects is designed to handle subscriptions for non-registered users.
5+
6+
A key feature of Prospects is its ability to manage subscriptions without requiring user registration. This makes it ideal for:
7+
- Newsletter subscriptions from website visitors
8+
- Blog update notifications for readers
9+
- Marketing communication preferences
10+
- Event notifications etc
11+
12+
Each email address can be subscribed to multiple activities simultaneously, allowing granular control over different types of communications. The system maintains subscription status and related details independently of Frontier's user authentication system.
13+
14+
### Key Fields
15+
- **Email**: Subscriber's email address
16+
- **Activity**: Type of subscription (newsletters, marketing emails, blog articles)
17+
- **Status**: Current subscription state (`subscribed` or `unsubscribed`)
18+
- **ChangedAt**: Timestamp of last status change (useful for metrics like monthly subscriber growth)
19+
- **Source**: Origin of subscription (`website`, `email`, `social-media`)
20+
- **Verified**: Email verification status (boolean)
21+
22+
## Access Control
23+
Admin users have full CRUD access.
24+
25+
Public access limited to prospect creation via the unauthenticated endpoint.
26+
27+
## API Reference
28+
29+
### Public Endpoints
30+
31+
#### Create a prospect (Unauthenticated)
32+
Endpoint: POST `/v1beta1/prospects`
33+
34+
RPC: `CreateProspectPublic`
35+
36+
Request:
37+
38+
```json
39+
{
40+
"email": "test@example.com",
41+
"activity": "newsletter",
42+
"source": "website"
43+
}
44+
```
45+
46+
Response:
47+
```json
48+
{
49+
"prospect": {
50+
"id": "id-1",
51+
"name": "",
52+
"email": "test@example.com",
53+
"phone": "",
54+
"activity": "newsletter",
55+
"status": "STATUS_SUBSCRIBED",
56+
"changed_at": "2025-03-04T07:23:52.611644Z",
57+
"source": "website",
58+
"verified": true,
59+
"created_at": "2025-03-04T07:23:52.611644Z",
60+
"updated_at": "2025-03-04T07:23:52.611644Z",
61+
"metadata": {}
62+
}
63+
}
64+
```
65+
### Admin endpoints
66+
67+
#### Create a prospect
68+
Endpoint: POST `/v1beta1/admin/prospects`
69+
70+
RPC: `CreateProspect`
71+
72+
Request:
73+
74+
```json5
75+
{
76+
"email": "test@example.com",
77+
"activity": "blog",
78+
"status": 1, // subscribed
79+
"source": "admin",
80+
"metadata": {
81+
"medium": "test"
82+
}
83+
}
84+
```
85+
86+
Response:
87+
```json
88+
{
89+
"prospect": {
90+
"id": "id-2",
91+
"name": "",
92+
"email": "test@example.com",
93+
"phone": "",
94+
"activity": "blog",
95+
"status": "STATUS_SUBSCRIBED",
96+
"changed_at": "2025-03-04T07:23:52.611644Z",
97+
"source": "admin",
98+
"verified": true,
99+
"created_at": "2025-03-04T07:23:52.611644Z",
100+
"updated_at": "2025-03-04T07:23:52.611644Z",
101+
"metadata": {"medium": "test"}
102+
}
103+
}
104+
```
105+
106+
#### Get Prospect
107+
Endpoint: GET `v1beta1/admin/prospects/{id}`
108+
109+
RPC: `GetProspect`
110+
111+
Request: `v1beta1/admin/prospects/id-1`
112+
113+
Response:
114+
```json
115+
{
116+
"prospect": {
117+
"id": "id-1",
118+
"name": "",
119+
"email": "test@example.com",
120+
"phone": "",
121+
"activity": "newsletter",
122+
"status": "STATUS_SUBSCRIBED",
123+
"changed_at": "2025-03-04T07:23:52.611644Z",
124+
"source": "website",
125+
"verified": true,
126+
"created_at": "2025-03-04T07:23:52.611644Z",
127+
"updated_at": "2025-03-04T07:23:52.611644Z",
128+
"metadata": {}
129+
}
130+
}
131+
```
132+
133+
#### List Prospects
134+
135+
Endpoint: POST `/v1beta1/admin/prospects/list`
136+
137+
RPC: `ListProspects`
138+
139+
Request:
140+
```json5
141+
{
142+
// filters, sorting, pagination and groups supported
143+
}
144+
```
145+
146+
Response:
147+
148+
```json
149+
{
150+
"prospects": [
151+
{
152+
"id": "id-1",
153+
"name": "",
154+
"email": "test@example.com",
155+
"phone": "",
156+
"activity": "newsletter",
157+
"status": "STATUS_SUBSCRIBED",
158+
"changed_at": "2025-03-04T07:23:52.611644Z",
159+
"source": "website",
160+
"verified": true,
161+
"created_at": "2025-03-04T07:23:52.611644Z",
162+
"updated_at": "2025-03-04T07:23:52.611644Z",
163+
"metadata": {}
164+
},
165+
{
166+
"id": "id-2",
167+
"name": "",
168+
"email": "test@example.com",
169+
"phone": "",
170+
"activity": "blog",
171+
"status": "STATUS_SUBSCRIBED",
172+
"changed_at": "2025-03-04T07:23:52.611644Z",
173+
"source": "admin",
174+
"verified": true,
175+
"created_at": "2025-03-04T07:23:52.611644Z",
176+
"updated_at": "2025-03-04T07:23:52.611644Z",
177+
"metadata": {"medium": "test"}
178+
}
179+
],
180+
"pagination": {
181+
"offset": 0,
182+
"limit": 2,
183+
"total_count": 5
184+
},
185+
"group": null
186+
}
187+
```
188+
189+
#### Update Prospect
190+
Endpoint: PUT `/v1beta1/admin/prospects/{id}`
191+
192+
RPC: `UpdateProspect`
193+
194+
Request:
195+
```json
196+
{
197+
"id": "id-1",
198+
"name": "updated-name",
199+
"email": "test@example.com",
200+
"phone": "",
201+
"activity": "newsletter",
202+
"status": 1,
203+
"source": "website",
204+
"verified": true,
205+
"metadata": {}
206+
}
207+
```
208+
209+
Response:
210+
```json
211+
{
212+
"prospect": {
213+
"id": "id-1",
214+
"name": "updated-name",
215+
"email": "test@example.com",
216+
"phone": "",
217+
"activity": "newsletter",
218+
"status": "STATUS_SUBSCRIBED",
219+
"changed_at": "2025-03-04T07:23:52.611644Z",
220+
"source": "website",
221+
"verified": true,
222+
"created_at": "2025-03-04T07:23:52.611644Z",
223+
"updated_at": "2025-03-05T07:23:52.611644Z",
224+
"metadata": {}
225+
}
226+
}
227+
```
228+
229+
#### Delete Prospect
230+
Endpoint: DELETE `/v1beta1/admin/prospects/{id}`
231+
232+
RPC: `DeleteProspect`
233+
234+
Request: `v1beta1/admin/prospects/id-1`
235+
236+
Response: `{}`

‎docs/sidebars.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,18 @@ module.exports = {
113113
"billing/billing_subscriptions"
114114
],
115115
},
116+
{
117+
type: "category",
118+
label: "Prospects",
119+
collapsed: true,
120+
link: {
121+
type: "doc",
122+
id: "prospects/introduction",
123+
},
124+
items: [
125+
"prospects/introduction",
126+
],
127+
},
116128
{
117129
type: "category",
118130
label: "APIs",

0 commit comments

Comments
 (0)