AgentHub Connect API
Lead ingestion API for real estate agencies — Version 1.0
1. Overview
The AgentHub Connect API is a high-performance integration point designed for real estate agencies to ingest leads directly from their websites into the AgentHub CRM.
This API is built to be flexible. It captures standard contact information while automatically handling any custom form questions (such as "Buyer Preferences" or "Key Agent Skills") without requiring database schema changes.
2. Authentication
Secure access is enforced via an API Key. You must include your unique Company API Key in the HTTP header of every request.
| Header | Required | Value | Description |
|---|---|---|---|
| x-api-key | Yes | YOUR_API_KEY | The 20-character secret key provided by your AgentHub account manager. |
| Content-Type | Yes | application/json | Ensures the payload is processed correctly. |
Security Note: If you are implementing on a public-facing website, use a server-side proxy (e.g., PHP, Node.js) to keep your API Key hidden from browser inspection.
3. Endpoint: Submit Lead
Submits a new buyer or vendor inquiry. The system instantly accepts the request (returning 200 OK) and processes deduplication and data entry asynchronously.
3.1 Mandatory Field
The API will reject the request if these core fields are missing.
| Field | Type | Description |
|---|---|---|
| first_name | String | The lead's first name. |
| last_name | String | The lead's last name. |
| String | Valid email address. Used as the unique identifier for deduplication. | |
| phone | String | Primary contact number. Parse and send in E.164 format (e.g., +61400000000). |
| board | String | The board identifier: lowercase, use underscores for spaces. See correlation below. |
| status | String | The status within the chosen board: lowercase, underscores for spaces. See correlation below. |
Board name → board value
- Leads → "lead"
- Buyers → "buyers"
- Past Buyers → "past_buyers"
- Cold Leads → "cold_leads"
Status name → status value
- New Lead → "new_lead"
- Contacted → "contacted"
- Qualified → "qualified"
- Converted → "converted"
Mandatory fields — type & example (vertical)
first_name
Type: String
Example: "Sarah"
last_name
Type: String
Example: "Jenkins"
Type: String
Example: "sarah.j@example.com"
phone
Type: String (E.164)
Example: "+61412345678"
board
Type: String
Example: "lead" (Leads), "buyers" (Buyers), "past_buyers" (Past Buyers), "cold_leads" (Cold Leads)
status
Type: String
Example: "new_lead" (New Lead), "contacted" (Contacted), "qualified" (Qualified), "converted" (Converted)
3.2 Standard Fields (Optional)
These fields are optional and map automatically to the main columns in the CRM.
| Field | Type | Description |
|---|---|---|
| budget | String | The buyer's property budget (e.g., "$1.5M", "800k"). |
| preferred_states | String or Array | Target Australian state(s), e.g. "QLD" or ["NSW", "QLD", "VIC"]. |
| timeline | String | Purchasing timeframe (e.g., "3-6 Months"). |
| message | String | Any text from the "Additional Details" or "Message" box. |
| campaign_name | String | Source tracking (e.g., "Website_Home_Form"). |
3.3 Custom Fields (Dynamic Mapping)
You can send any additional JSON key-value pairs. AgentHub will store them in the custom_fields section. You do not need to register these fields in advance.
Common examples: whatsapp_number, current_location, preferred_contact_time, preferred_states (Array of Australian state codes, e.g. ["NSW", "QLD", "VIC"]).
4. Example Implementation
JSON Payload Example
{
"first_name": "Sarah",
"last_name": "Jenkins",
"email": "sarah.j@example.com",
"phone": "+61412345678",
"board": "lead",
"status": "new_lead",
"budget": "$800k-$1M",
"timeline": "Within 6 months",
"message": "Looking for a family home with backyard.",
"current_location": "Brisbane, QLD",
"preferred_contact_time": "Weekdays 9am-5pm",
"looking_for": "First Home",
"preferred_states": ["NSW", "QLD", "VIC"]
}Code snippets by language
curl -X POST "https://prod.api.agenthub.au/company/NewLead" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_ASSIGNED_API_KEY" \
-d '{"first_name":"Sarah","last_name":"Jenkins","email":"sarah.j@example.com","phone":"+61412345678","board":"lead","status":"new_lead","budget":"$800k-$1M","timeline":"Within 6 months","message":"Looking for a family home with backyard.","current_location":"Brisbane, QLD","preferred_contact_time":"Weekdays 9am-5pm","looking_for":"First Home","preferred_states":["NSW","QLD","VIC"]}'5. API Response Codes
| Status Code | Message | Meaning |
|---|---|---|
| 200 OK | Lead received successfully | Success. The lead is queued for processing. |
| 400 Bad Request | Invalid JSON | The request body was malformed. |
| 403 Forbidden | Forbidden | The API Key is invalid or missing. |
| 500 Server Error | Internal Server Error | Something went wrong on the server side. |
6. Support & Rate Limits
- Rate Limit: 10 requests per second (Standard Tier).
- Deduplication: Duplicate emails for the same company are automatically merged; no duplicate
lead_idwill be generated. - For integration assistance or to request a higher rate limit, contact support@agenthub360.com.au.