Skip to content

Commit e509f53

Browse files
ucswiftucswift
authored
Merge pull request #33 from Resgrid/develop
Develop
2 parents d99d2e5 + a7e73e5 commit e509f53

27 files changed

Lines changed: 4886 additions & 69 deletions

‎docs/api/contact-verification.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
5+
# Contact Verification API
6+
7+
The Contact Verification API allows clients to programmatically send verification codes and confirm contact methods for the authenticated user. These endpoints are used by the profile UI to manage email, mobile number, and home number verification inline.
8+
9+
## Authentication
10+
11+
All Contact Verification API endpoints require a valid JWT token. See [API Authentication](authentication) for details.
12+
13+
**Base URL:** `/api/v4/ContactVerification`
14+
15+
## Send Verification Code
16+
17+
Sends a verification code to the specified contact method for the authenticated user. For email, a verification email is sent. For mobile and home numbers, an SMS is sent.
18+
19+
```
20+
POST /api/v4/ContactVerification/SendVerificationCode
21+
```
22+
23+
**Request Body:**
24+
25+
| Field | Type | Required | Description |
26+
|-------|------|----------|-------------|
27+
| `Type` | int | Yes | Contact verification type: `0` = Email, `1` = MobileNumber, `2` = HomeNumber |
28+
29+
**Response:**
30+
31+
| Field | Type | Description |
32+
|-------|------|-------------|
33+
| `Success` | bool | Whether the code was sent successfully |
34+
| `Message` | string | Descriptive message (e.g., "A verification code has been sent." or an error message) |
35+
36+
**Error Scenarios:**
37+
38+
| HTTP Status | Condition |
39+
|-------------|-----------|
40+
| `200 OK` | Code sent successfully, or a descriptive error in the response body |
41+
| `429 Too Many Requests` | Rate limit exceeded (max 3 sends per contact method per hour) |
42+
| `400 Bad Request` | Invalid contact type or no contact value on file |
43+
44+
**Example Request:**
45+
46+
```bash
47+
curl -X POST \
48+
-H "Authorization: Bearer <access_token>" \
49+
-H "Content-Type: application/json" \
50+
"https://api.resgrid.com/api/v4/ContactVerification/SendVerificationCode" \
51+
-d '{"Type": 0}'
52+
```
53+
54+
**Example Response:**
55+
56+
```json
57+
{
58+
"Data": {
59+
"Success": true,
60+
"Message": "A verification code has been sent."
61+
},
62+
"Status": "success"
63+
}
64+
```
65+
66+
## Confirm Verification Code
67+
68+
Validates a verification code entered by the user and, if correct and not expired, marks the contact method as verified.
69+
70+
```
71+
POST /api/v4/ContactVerification/ConfirmVerificationCode
72+
```
73+
74+
**Request Body:**
75+
76+
| Field | Type | Required | Description |
77+
|-------|------|----------|-------------|
78+
| `Type` | int | Yes | Contact verification type: `0` = Email, `1` = MobileNumber, `2` = HomeNumber |
79+
| `Code` | string | Yes | The 6-digit numeric verification code |
80+
81+
**Response:**
82+
83+
| Field | Type | Description |
84+
|-------|------|-------------|
85+
| `Success` | bool | Whether the verification was successful |
86+
| `Message` | string | Descriptive message (e.g., "Verification successful." or an error message) |
87+
88+
**Error Scenarios:**
89+
90+
| HTTP Status | Condition |
91+
|-------------|-----------|
92+
| `200 OK` | Verification confirmed or a descriptive error in the response body |
93+
| `429 Too Many Requests` | Daily attempt limit exceeded (max 5 attempts per contact method per day) |
94+
| `400 Bad Request` | Invalid contact type or missing code |
95+
96+
**Example Request:**
97+
98+
```bash
99+
curl -X POST \
100+
-H "Authorization: Bearer <access_token>" \
101+
-H "Content-Type: application/json" \
102+
"https://api.resgrid.com/api/v4/ContactVerification/ConfirmVerificationCode" \
103+
-d '{"Type": 1, "Code": "482910"}'
104+
```
105+
106+
**Example Response (Success):**
107+
108+
```json
109+
{
110+
"Data": {
111+
"Success": true,
112+
"Message": "Verification successful."
113+
},
114+
"Status": "success"
115+
}
116+
```
117+
118+
**Example Response (Failure):**
119+
120+
```json
121+
{
122+
"Data": {
123+
"Success": false,
124+
"Message": "Verification failed. Please check the code and try again."
125+
},
126+
"Status": "success"
127+
}
128+
```
129+
130+
## Contact Verification Types
131+
132+
| Value | Name | Description |
133+
|-------|------|-------------|
134+
| `0` | Email | Email address verification (sends verification email) |
135+
| `1` | MobileNumber | Mobile number verification (sends SMS) |
136+
| `2` | HomeNumber | Home number verification (sends SMS) |
137+
138+
## Rate Limits
139+
140+
| Limit | Default | Description |
141+
|-------|---------|-------------|
142+
| Max sends per hour | 3 | Maximum verification code sends per contact method per hour |
143+
| Max attempts per day | 5 | Maximum verification code entry attempts per contact method per day |
144+
| Code expiry | 30 minutes | How long a verification code remains valid |
145+
146+
When a rate limit is reached, the API returns an appropriate error message. Daily attempt counters reset at midnight UTC.
147+
148+
## Verification State Model
149+
150+
Each contact method on a user profile has a tri-state verification value:
151+
152+
| Value | State | Communications |
153+
|-------|-------|---------------|
154+
| `null` | Grandfathered | Allowed (pre-existing users) |
155+
| `false` | Pending | Blocked until verified |
156+
| `true` | Verified | Allowed |
157+
158+
For more details on how verification affects dispatches, notifications, and messaging, see the [Contact Method Verification](../configuration/contact-verification) configuration guide.

0 commit comments

Comments
 (0)