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": "+14766592691",
"created_at": 1787792222.734486,
"id": "6ee3e23e-a255-4976-b467-fe1eb66d168c",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/6ee3e23e-a255-4976-b467-fe1eb66d168c/38393580-a1b2-11f1-811e-f93126d9eb55.jpg",
"profile_image_url": "https://test.cloudfront.net/6ee3e23e-a255-4976-b467-fe1eb66d168c/383e1780-a1b2-11f1-811e-f93126d9eb55.jpg",
"updated_at": 1787792224.510368,
"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": "b83179c7-d5e6-4765-923a-d8892a066e81",
"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": "7:57 PM - Wednesday Aug 26, 2026",
"push_allowed": true,
"agents": [
{
"id": "7363af60-f40c-4d58-9ce8-6511a914ae6e",
"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": "710038812",
"updated_at": 1787792222.852221,
"deleted_at": null,
"created_at": 1787792222.852221,
"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-b66a1aba-cecb-490e-a554-537e48886ab2%40rechat.com?issuer=Rechat&secret=CTVRHMGBIXCLRYYYQOG3BR3IHGKVQYUL&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": "542672"
}200Body
{
"code": "OK",
"data": {
"type": "user",
"username": null,
"first_name": "updated first name",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+14766592691",
"created_at": 1787792222.734486,
"id": "6ee3e23e-a255-4976-b467-fe1eb66d168c",
"address_id": null,
"cover_image_url": "https://test.cloudfront.net/6ee3e23e-a255-4976-b467-fe1eb66d168c/38393580-a1b2-11f1-811e-f93126d9eb55.jpg",
"profile_image_url": "https://test.cloudfront.net/6ee3e23e-a255-4976-b467-fe1eb66d168c/383e1780-a1b2-11f1-811e-f93126d9eb55.jpg",
"updated_at": 1787792224.510368,
"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": "b83179c7-d5e6-4765-923a-d8892a066e81",
"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": "7:57 PM - Wednesday Aug 26, 2026",
"push_allowed": true,
"agents": [
{
"id": "7363af60-f40c-4d58-9ce8-6511a914ae6e",
"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": "710038812",
"updated_at": 1787792222.852221,
"deleted_at": null,
"created_at": 1787792222.852221,
"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
}
}