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
200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+18414462616",
"created_at": 1791656564.753662,
"id": "dd61f180-2831-4496-b575-36b18545fd11",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/dd61f180-2831-4496-b575-36b18545fd11/9700c9a0-c4d7-11f1-89da-fb554657817f.jpg",
"profile_image_url": "https://test.cloudfront.net/dd61f180-2831-4496-b575-36b18545fd11/9703d6e0-c4d7-11f1-89da-fb554657817f.jpg",
"updated_at": 1791656565.584941,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": false,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": false,
"is_shadow": false,
"personal_room": "cc87acf8-82bd-400e-ba94-9786b66dd370",
"brand": null,
"fake_email": null,
"features": null,
"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": null,
"bio": "Here is my great bio",
"current_time": "1:22 PM - Saturday Oct 10, 2026",
"push_allowed": true,
"agents": [
{
"id": "58469a15-6b61-4ec0-8825-0c4935bbc8d9",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "+19722644703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "+14693588080",
"generational_name": null,
"matrix_unique_id": "91589353",
"updated_at": 1791656564.811259,
"deleted_at": null,
"created_at": 1791656564.811259,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"+1XXXXXXXX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Doe",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"mfa_url": "otpauth://totp/Rechat:test-user-6989d990-aafd-4421-882f-a6afb8deec5b%40rechat.com?issuer=Rechat&secret=3ENKZSY2C6AX4LF6QCPUHJDVHMTCHHQQ&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
Body
{
"token": "589362"
}200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+18414462616",
"created_at": 1791656564.753662,
"id": "dd61f180-2831-4496-b575-36b18545fd11",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/dd61f180-2831-4496-b575-36b18545fd11/9700c9a0-c4d7-11f1-89da-fb554657817f.jpg",
"profile_image_url": "https://test.cloudfront.net/dd61f180-2831-4496-b575-36b18545fd11/9703d6e0-c4d7-11f1-89da-fb554657817f.jpg",
"updated_at": 1791656565.584941,
"user_status": "Active",
"profile_image_thumbnail_url": null,
"cover_image_thumbnail_url": null,
"email_confirmed": false,
"timezone": "America/Chicago",
"user_type": "Agent",
"deleted_at": null,
"phone_confirmed": false,
"is_shadow": false,
"personal_room": "cc87acf8-82bd-400e-ba94-9786b66dd370",
"brand": null,
"fake_email": null,
"features": null,
"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": null,
"bio": "Here is my great bio",
"current_time": "1:22 PM - Saturday Oct 10, 2026",
"push_allowed": true,
"agents": [
{
"id": "58469a15-6b61-4ec0-8825-0c4935bbc8d9",
"email": "[email protected]",
"mlsid": "00920130",
"fax": "(972) 264-4703",
"full_name": "Gholi Sweet",
"first_name": "Gholi",
"last_name": "Sweet",
"middle_name": null,
"phone_number": "+19722644703",
"nar_number": "797500044",
"office_mui": "15512742",
"status": "Active",
"office_mlsid": "RCHT01X",
"work_phone": "+14693588080",
"generational_name": null,
"matrix_unique_id": "91589353",
"updated_at": 1791656564.811259,
"deleted_at": null,
"created_at": 1791656564.811259,
"mls": "NTREIS",
"license_number": null,
"designation": null,
"nrds": "01053140",
"type": "agent",
"office_id": null,
"secret_questions": [
"(972) XXX-XX03",
"jewellxxxxxxxxxxxxxal.net",
"+1XXXXXXXX80"
]
}
],
"last_seen_type": null,
"active_brand": null,
"display_name": "updated first name Doe",
"abbreviated_display_name": "updated first name",
"online_state": "Offline",
"has_password": true
}
}