Key Benefits
The Radius Integration API for Client Import provides:
Automated client data syncing – Import client records directly into Radius from third-party CRM systems
Comprehensive data import – Create or update clients along with associated property and requirement information in a single API call
Smart de-duplication – Automatically merges records with matching email or phone numbers to prevent duplicates
Flexible data structure – Supports multiple emails, phone numbers, tags, and custom fields for complete client profiles
Secure authentication – Account-specific integration keys ensure data security and proper authorization
Seamless CRM integration – Connect your existing systems to Radius without manual data entry
Step-by-Step Instructions
Prerequisites
Before using the Radius Integration API, ensure you have:
Access to your Radius account with administrative permissions
A third-party CRM or system capable of making API calls
Basic understanding of API integrations and JSON formatting
Step 1: Retrieve Your Integration Key (secure-id)
The secure-id is your account-specific authentication key required for all API requests.
Log in to your Radius account
Navigate to Settings
Click on the Integrations tab
Search for "Radius agent API key"
Copy your Integration Key / secure-id for use in API requests
Important: Keep your secure-id confidential and store it securely. This key grants access to import data into your Radius account.
Step 2: Prepare Your API Request
Endpoint URL:
https://api1.agentdesks.com/v3.0/clients/import
Method: POST
Protocol: HTTPS
Required Headers:
Header Name | Value | Description |
Content-Type | application/json | Specifies JSON payload format |
secure-id | [Your Integration Key] | Account-specific authentication key |
Step 3: Structure Your Request Payload
The request body must be valid JSON with the following top-level keys:
client (required) – Contains client information
prop (optional) – Contains property details for sellers
req (optional) – Contains buyer search criteria/requirements
Sample Request Payload:
json
{ "client": { "name": "Sample Client Name", "type": "buyer", "status": "Showings/Tours", "emails": "client@example.com", "phones": "5551234567", "address": "Financial District, San Francisco, CA", "city": "San Francisco", "zipcode": "94105", "state": "California", "tags": ["buyer", "important"], "source": "other_agency", "gender": "", "location": "San Francisco, CA", "date_of_birth": "1985-06-15", "spouse_date_of_birth": "1987-03-20", "home_anniversary": "2020-05-10", "company_name": "ABC Company", "attorney_name": "John Smith", "commission": "3", "priority_status": "high", "website": "https://www.example.com/" }, "prop": { "address": "123 Main St, Stanford, CA 94305, USA", "property_name": "123 Main Street", "prop_city": "Stanford", "prop_state": "California", "prop_zipcode": "94305", "no_of_bed_room": 3, "no_of_bath_room": 2, "property_age": 15, "covered_area": 2500, "area_coverage": "Sq.ft", "resale_price": 850000, "property_type": "single_family", "country": "United States" }, "req": { "city": "Palo Alto", "state": "California", "min_budget": 700000, "max_budget": 1200000, "bedroom": 3, "bathroom": 2, "area_unit": "Sq.ft", "zipcode": "94301", "c_locality_name": "Downtown Palo Alto", "country": "United States" } }Step 4: Understanding Data Field Requirements
Client Type Values:
Must be one of the following:
sellerbuyertenantlandlord
Multiple Emails and Phone Numbers:
Use comma-separated values to include multiple contact methods:
json
"emails": "email1@example.com,email2@example.com", "phones": "5551234567,5559876543"
Phone Number Format Requirements:
Must be exactly 10 digits
Do NOT include country code
Do NOT include spaces, dashes, or special characters
✅ Correct:
"5551234567"❌ Incorrect:
"+1 555-123-4567"or"555 123 4567"
Property Data (prop):
Use the prop key to include seller property information. This is optional but recommended for seller clients.
Search Criteria (req):
Use the req key to include buyer search criteria and requirements. This is optional but recommended for buyer clients.
Step 5: Send the API Request
Using your preferred API client or integration platform:
Set the endpoint URL to
https://api1.agentdesks.com/v3.0/clients/importSet the method to POST
Add the required headers (Content-Type and secure-id)
Include your JSON payload in the request body
Send the request
Step 6: Handle API Responses
Successful Import:
When the client is successfully imported or updated, you'll receive a success response from the API.
Error Responses:
The API returns structured error messages when validation fails. Common errors include:
Missing Client Name (Error Code 101):
json
{ "error": { "message": "Missing Client name", "code": 101 } }Missing Client Email (Error Code 102):
json
{ "error": { "message": "Missing Client Email", "code": 102 } }Missing Client Phone Number (Error Code 103):
json
{ "error": { "message": "Missing Client PhoneNumber", "code": 103 } }Empty Request Body (Error Code 400):
json
{ "error": { "message": "Empty Input Request", "code": 400 } }Best Practices
Validate mandatory fields – Always include client name, at least one email, and at least one phone number in every request
Format phone numbers correctly – Use exactly 10 digits with no special characters or country codes
Test with sample data first – Before importing production data, test your integration with sample client records
Handle errors gracefully – Implement error handling in your integration to retry or log failed imports
Use consistent data formatting – Maintain consistent date formats, address structures, and field values across all imports
Leverage de-duplication – The API automatically merges clients with matching emails or phone numbers, preventing duplicates
Include relevant optional data – Add property information for sellers and search criteria for buyers to create complete client profiles
Secure your API key – Store your secure-id securely and never expose it in client-side code or public repositories
Monitor import success – Regularly review import logs to ensure data is syncing correctly
Document your field mappings – Keep a record of how your CRM fields map to Radius fields for future reference