API Documentation
Multi-factor authentication ¶
Overview
MFA is an opt-in feature, allowing users to set it up in their account settings. Once MFA is activated, MFA will be required when making certain API requests, such as changing the password.
-
Setup MFA: To get started, make a
POSTrequest to/users/self/mfa/setup. This endpoint will return two important fields,mfa_urlandmfa_qr_code, which can be used with an authenticator application to add a new service. -
Verify MFA:
POST /users/self/mfa/verifyAfter setting up MFA, it’s not immediately enabled for the user. We require users to verify it first by providing a token. The verification step enables the MFA for the user and also marks the current access_token/refresh_token pair as MFA validated. -
Validate MFA: If a user with verified MFA needs to sign in again, the new access_token/refresh_token pair won’t be MFA validated by default. This means that every request made with the access token will result in a
401 MFA required error. In such cases, the client must callPOST /users/self/mfa/validatewith a valid MFA token generated by the authenticator application to mark the tokens as MFA validated. -
Delete MFA:
DELETE /users/self/mfaendpoint with a valid MFA token can be used to remove the multi-factor authentication from the user.
Setup MFA ¶
Setup MFAPOST/users/self/mfa/setup
Example URI
POST /users/self/mfa/setup
Response
200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Test",
"email": "[email protected]",
"phone_number": "+4368120265807",
"created_at": 1493115498.770362,
"id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/045fa3a0-5092-11f1-8248-cf8ab660e2ca.jpg",
"profile_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/0467b9f0-5092-11f1-8248-cf8ab660e2ca.jpg",
"updated_at": 1778872349.463336,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": true,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": true,
"is_shadow": false,
"personal_room": null,
"brand": null,
"fake_email": false,
"features": [
"Deals"
],
"last_seen_at": null,
"email_signature": "Here is my great signature",
"daily_enabled": true,
"email_quota": 30000,
"website": null,
"instagram": null,
"twitter": null,
"linkedin": null,
"youtube": null,
"facebook": null,
"designation": null,
"tiktok": null,
"mfa_enabled": false,
"xpressdocs_user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
"current_time": "2:12 PM - Friday May 15, 2026",
"push_allowed": true,
"agents": [
{
"id": "c5136d4f-9468-4c2a-a756-3cc3a9db1c9a",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "(972) 264-4703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "(469) 358-8080",
"generational_name": null,
"matrix_unique_id": "155155530",
"updated_at": 1778872347.477071,
"deleted_at": null,
"created_at": 1778872347.477071,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"(469) XXX-XX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Test",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"mfa_url": "otpauth://totp/Rechat:test%40rechat.com?issuer=Rechat&secret=TWPBFEMBHK4Y643MZXUVJKKX3WJFBPCL&algorithm=SHA1&digits=6&period=30",
"mfa_qr_code": "data:image/png;base64,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",
"has_password": true
}
}Verify MFA after setup ¶
Verify MFA after setupPOST/users/self/mfa/verify
Example URI
POST /users/self/mfa/verify
Request
Body
{
"token": "018988"
}Response
200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Test",
"email": "[email protected]",
"phone_number": "+4368120265807",
"created_at": 1493115498.770362,
"id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/045fa3a0-5092-11f1-8248-cf8ab660e2ca.jpg",
"profile_image_url": "https://test.cloudfront.net/80a227b2-29a0-11e7-b636-e4a7a08e15d4/0467b9f0-5092-11f1-8248-cf8ab660e2ca.jpg",
"updated_at": 1778872349.463336,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": true,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": true,
"is_shadow": false,
"personal_room": null,
"brand": null,
"fake_email": false,
"features": [
"Deals"
],
"last_seen_at": null,
"email_signature": "Here is my great signature",
"daily_enabled": true,
"email_quota": 30000,
"website": null,
"instagram": null,
"twitter": null,
"linkedin": null,
"youtube": null,
"facebook": null,
"designation": null,
"tiktok": null,
"mfa_enabled": true,
"xpressdocs_user_id": "80a227b2-29a0-11e7-b636-e4a7a08e15d4",
"current_time": "2:12 PM - Friday May 15, 2026",
"push_allowed": true,
"agents": [
{
"id": "c5136d4f-9468-4c2a-a756-3cc3a9db1c9a",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "(972) 264-4703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "(469) 358-8080",
"generational_name": null,
"matrix_unique_id": "155155530",
"updated_at": 1778872347.477071,
"deleted_at": null,
"created_at": 1778872347.477071,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"(469) XXX-XX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Test",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"has_password": true
}
}