Skip to content

Commit d5b01cc

Browse files
xiadongdevxiadongdev
authored
chore: add information about describe-user response (#7)
1 parent b9ed7ef commit d5b01cc

1 file changed

Lines changed: 131 additions & 1 deletion

File tree

‎reference/api-reference.md‎

Lines changed: 131 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,137 @@ GET https://account.api.visualping.io/describe-user
7373
Authorization: Bearer <token>
7474
```
7575

76-
Returns information about the authenticated user.
76+
Returns information about the authenticated user, including their profile and workspaces. Business users also receive an `organisation` section.
77+
78+
#### Response Fields
79+
80+
| Field | Type | Description |
81+
| ------------------------- | ------- | ---------------------------------------------------------- |
82+
| `userId` | integer | Unique user ID |
83+
| `emailAddress` | string | User's email address |
84+
| `country` | string | User's country |
85+
| `locale` | string | Locale code (e.g. `en`) |
86+
| `timeZone` | string | User's time zone (e.g. `America/Vancouver`) |
87+
| `loginCount` | integer | Total number of logins |
88+
| `signUpAgeDays` | integer | Days since sign-up |
89+
| `intentForBusiness` | boolean | Whether the user signed up for business use |
90+
| `googleChatIntegrated` | boolean | Google Chat integration status |
91+
| `googleSheetsIntegrated` | boolean | Google Sheets integration status |
92+
| `slackInstallationStatus` | object | Slack installation details |
93+
| `refreshToken` | boolean | Whether a refresh token is present |
94+
| `organisation` | object | Organisation details — **business users only** (see below) |
95+
| `workspaces` | array | List of workspaces the user belongs to (see below) |
96+
97+
##### `organisation` object
98+
99+
| Field | Type | Description |
100+
| ----------------------------- | ----------------- | ---------------------------------------------- |
101+
| `id` | integer | Organisation ID |
102+
| `name` | string | Organisation name |
103+
| `timeZone` | string | Organisation time zone |
104+
| `role` | string | User's role in the organisation (e.g. `ADMIN`) |
105+
| `plan` | object | Current subscription plan details |
106+
| `userHasPersonalSubscription` | boolean | Whether the user has a personal subscription |
107+
| `accountFeatures` | object | Feature flags and limits for the organisation |
108+
| `balances` | object | Credit balance and renewal info |
109+
| `counts` | object | Active job and user counts |
110+
| `trialStartDate` | string (ISO 8601) | Trial start date |
111+
| `trialEndDate` | string (ISO 8601) | Trial end date |
112+
| `orgCreatedAt` | string (ISO 8601) | Organisation creation date |
113+
114+
##### `workspaces` array items
115+
116+
| Field | Type | Description |
117+
| --------------------- | ------- | ------------------------------------------------- |
118+
| `id` | integer | Workspace ID |
119+
| `name` | string | Workspace name |
120+
| `timeZone` | string | Workspace time zone |
121+
| `role` | string | User's role in this workspace (e.g. `ADMIN`) |
122+
| `plan` | object | Workspace subscription plan |
123+
| `accountFeatures` | object | Feature flags and limits for this workspace |
124+
| `balances` | object | Credit balance including `inOverConsumption` flag |
125+
| `counts` | object | Active job and user counts |
126+
| `notificationMembers` | array | List of CC email recipients for notifications |
127+
| `status` | string | Workspace status (e.g. `active`) |
128+
129+
#### Example Response
130+
131+
```json
132+
{
133+
"userId": 123456,
134+
"emailAddress": "user@example.com",
135+
"country": "Canada",
136+
"locale": "en",
137+
"timeZone": "America/Vancouver",
138+
"loginCount": 77,
139+
"slackInstallationStatus": {},
140+
"refreshToken": false,
141+
"organisation": {
142+
"id": 137388,
143+
"name": "Visualping",
144+
"timeZone": "America/Vancouver",
145+
"role": "ADMIN",
146+
"plan": {
147+
"name": "trial_2022.1_active",
148+
"type": "plan",
149+
"subType": "trial_active",
150+
"credits": 500,
151+
"billingPeriod": "monthly",
152+
"label": "Free trial"
153+
},
154+
"userHasPersonalSubscription": false,
155+
"accountFeatures": {
156+
"reports": { "enabled": true },
157+
"exports": { "enabled": true },
158+
"bulkImport": { "enabled": true },
159+
"ccEmails": { "enabled": true, "maxAddressCount": 5 },
160+
"sms": { "enabled": true },
161+
"advancedNotifications": { "enabled": true },
162+
"maxActiveJobsPerWorkspace": { "value": 25 },
163+
"maxJobFrequency": { "value": 1 },
164+
"emailSupport": { "enabled": true },
165+
"dedicatedSupport": { "enabled": true }
166+
},
167+
"balances": {
168+
"nextCreditRenewalAt": "2026-06-11T19:19:59.170Z",
169+
"estimatedMonthlyConsumption": 774
170+
},
171+
"counts": {
172+
"activeJobCount": 2,
173+
"activeJobFreeCount": 23,
174+
"activeJobOverflow": false,
175+
"activeUserCount": 4,
176+
"activeUserFreeCount": 6,
177+
"activeUserOverflow": false
178+
},
179+
"trialStartDate": "2026-05-07T19:19:59.170Z",
180+
"trialEndDate": "2026-05-21T19:19:59.170Z",
181+
"orgCreatedAt": "2026-05-07T19:19:59.000Z"
182+
},
183+
"workspaces": [
184+
{
185+
"id": 137389,
186+
"name": "Workspace #1",
187+
"timeZone": "America/Vancouver",
188+
"role": "ADMIN",
189+
"plan": { "name": "trial_2022.1_active", "label": "Free trial" },
190+
"balances": {
191+
"credits": 146,
192+
"nextCreditRenewalAt": "2055-11-21T19:19:59.170Z",
193+
"estimatedMonthlyConsumption": 732,
194+
"inOverConsumption": true
195+
},
196+
"counts": {
197+
"activeJobCount": 1,
198+
"activeJobFreeCount": 499999,
199+
"activeJobOverflow": false
200+
},
201+
"notificationMembers": [{ "type": "ccEmail", "value": "user@example.com", "confirmed": true }],
202+
"status": "active"
203+
}
204+
]
205+
}
206+
```
77207

78208
---
79209

0 commit comments

Comments
 (0)