Batdongsan Agent API Documentation

GET https://scrappa.co/api/batdongsan/agent

Batdongsan Agent API returns the profile of a publisher: name, photos, company, certificate number and expiry, awards, social links, how long the agent has been active, the number of listings and the views of the last 30 days.

Good to know:

Take agent_id from author.agent_id in search and listing results or from the top agents route. A numeric author id is not accepted and returns 422.
The site offers no list of the listings of one agent, so this route returns only the listing count.
The phone number stays masked.

Run this endpoint

Batdongsan Agent API Documentation 1 credit/request

Get API key Open Playground

Request preview

GET

https://scrappa.co/api/batdongsan/agent

Auth header: x-api-key
Cost: 1 credit/request

agent_id = 1234567890

Response preview

200 OK

{
    "data": {
        "id": 4752932,
        "name": "Th\u1ebf H\u00f9ng",
        "awards": [],
        "address": null,
        "company": {
            "name": null,
            "image_url": null
        },
        "socials": {
            "tiktok": null,
            "website": null,
            "youtube": null,
...

Parameters

Start with the required fields, then add optional filters only when your use case needs them.

Runnable path

1 required parameter needed before sending a request.

agent_id

agent_id


                                        string

Required

Profile id of the agent, for example 200810374fc3900f.

Example value

1234567890

Response Schema

Example response fields are illustrative; inspect the JSON before integrating.

Open in Playground

Example response fields

Scan these fields before integrating.

data meta success

JSON Response

200 OK

{
    "data": {
        "id": 4752932,
        "name": "Th\u1ebf H\u00f9ng",
        "awards": [],
        "address": null,
        "company": {
            "name": null,
            "image_url": null
        },
        "socials": {
            "tiktok": null,
            "website": null,
            "youtube": null,
            "facebook": null
        },
        "agent_id": "thehung",
        "avatar_url": "https://file4.batdongsan.com.vn/2025/10/23/20251023103146-f33a.jpg",
        "certificate": {
            "number": "TQ-0305",
            "expires": "2029-07-25T00:00:00",
            "has_certificate": true
        },
        "description": null,
        "friendly_id": "thehung",
        "profile_url": "https://guru.batdongsan.com.vn/pa/thehung",
        "is_pro_agent": true,
        "phone_masked": "0985262***",
        "listing_count": 21,
        "cover_image_url": null,
        "highlighted_post": null,
        "social_image_url": "https://file4.batdongsan.com.vn/2026/04/28/20260428144634-27cc.jpg",
        "joined_duration_years": 1,
        "listing_views_last_30_days": 1257
    },
    "meta": {
        "billable": true,
        "endpoint_family": "agent"
    },
    "success": true
}

Errors

Handle these documented responses before retrying or showing customer-facing failures.

422

Validation Error

A value is missing, unknown or out of range. Examples: an unknown province code, a category that does not exist for the listing type, or a reversed range. This response is not billed.

{
    "errors": {
        "city": [
            "The selected city is invalid."
        ]
    },
    "message": "The request validation failed"
}

404

Not Found

The agent does not exist. This response is not billed.

{
    "meta": {
        "billable": false,
        "retryable": false,
        "endpoint_family": "agent"
    },
    "error": {
        "code": "NOT_FOUND",
        "message": "The requested resource was not found."
    },
    "success": false
}

503

Upstream Unavailable

Batdongsan could not be reached or returned data that does not match the request. Retry shortly. This response is not billed.

{
    "meta": {
        "billable": false,
        "retryable": true,
        "endpoint_family": "agent"
    },
    "error": {
        "code": "UPSTREAM_UNAVAILABLE",
        "message": "Batdongsan could not be reached. Please retry shortly."
    },
    "success": false
}

Generate Code with AI

Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.

Try It Live

Test this endpoint in our interactive playground with real data.