# WhatsApp Profile Avatar API - Age & Gender (`clearpath/whatsapp-profile-avatar-age-gender-api`) Actor Analyze WhatsApp phone numbers for profile avatar URL, WhatsApp presence, inferred age, gender, image category, hair color, and skin tone. Upload CSV/XLSX or paste numbers. - **URL**: https://apify.com/clearpath/whatsapp-profile-avatar-age-gender-api.md - **Developed by:** [ClearPath](https://apify.com/clearpath) (community) - **Categories:** Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.50 / 1,000 profiles This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## WhatsApp Profile Avatar, Age & Gender API Check WhatsApp phone numbers in bulk and enrich profiles with avatar-based signals. The actor processes 100 to 10,000 unique numbers per real run. Larger inputs are deduped, then trimmed to the first 10,000 unique normalized numbers. It returns WhatsApp presence, avatar URL, avatar analysis status, estimated age, inferred gender, image category, hair color, and skin tone. Age, gender, hair color, and skin tone are inferred from profile images. Treat them as enrichment signals, not verified demographic facts.
Analyze up to 10,000 WhatsApp numbers per run with avatar URL, WhatsApp presence, inferred age/gender, image category, hair color, and skin tone in one result file.
Clearpath Phone Intelligence   •  Bulk validation and profile enrichment for messaging platforms
 WhatsApp Number Validator
Bulk WhatsApp yes/no checks 		 Telegram Number Validator
Bulk Telegram account checks 		Phone Active Status Checker
Carrier-level active checks 		MAX Messenger Number Checker
Bulk MAX account checks 		Social & Crypto Number Checker
25-platform account checks
#### Copy to your AI assistant Copy this block into ChatGPT, Codex, Cursor, or any LLM to start using this actor. ```` clearpath/whatsapp-profile-avatar-age-gender-api on Apify. Call: ApifyClient("TOKEN").actor("clearpath/whatsapp-profile-avatar-age-gender-api").call(run\_input={...}), then client.dataset(run\["defaultDatasetId"]).list\_items().items for results. Key inputs: testMode (boolean sample output), phoneNumbers (array of phone numbers) or csvFile (CSV/XLSX upload URL or key), defaultCountryCode (prepend country code for numbers without +), onlyWhatsappUsers (boolean filter). Full actor spec (input schema with all params/enums/defaults, output dataset fields, README): GET https://api.apify.com/v2/acts/clearpath~whatsapp-profile-avatar-age-gender-api/builds/default (Bearer TOKEN) → inputSchema (JSON string, parse it), actorDefinition.storages.dataset.views.overview.transformation.fields (output field list), readme. Real runs require testMode=false and at least 100 unique normalized numbers; inputs above 10,000 unique numbers are trimmed to the first 10,000 after dedupe. Get token: https://console.apify.com/account/integrations ```` ### Quick Start Preview sample output without charges: ```json { "testMode": true, "phoneNumbers": ["+14155552671"] } ```` Analyze a direct list: ```json { "testMode": false, "phoneNumbers": [ "+14155552671", "+442071234567" ], "onlyWhatsappUsers": false } ``` Upload CSV/XLSX and apply a default country code: ```json { "testMode": false, "csvFile": "uploaded-file.csv", "defaultCountryCode": "1", "onlyWhatsappUsers": true } ``` ### Input For real runs, at least one of `phoneNumbers` or `csvFile` is required. The actor is fully hosted on Apify. You provide phone numbers or an uploaded file; no extra credentials are required. | Parameter | Type | Description | |-----------|------|-------------| | `testMode` | boolean | Returns sample output without analyzing real numbers or charging credits. | | `phoneNumbers` | array | Phone numbers with country code. Real runs require at least 100 unique numbers and process the first 10,000 after dedupe. | | `csvFile` | string | Uploaded CSV or Excel file with phone numbers. | | `defaultCountryCode` | string | Country code to prepend to numbers without a `+` prefix. | | `onlyWhatsappUsers` | boolean | Output only numbers where `hasWhatsapp` is true. | ### Output ```json { "phoneNumber": "+14155552671", "originalInput": "+1 415 555 2671", "countryCode": "US", "isValidFormat": true, "hasWhatsapp": true, "hasAvatar": true, "avatarUrl": "https://placehold.co/128x128.jpg", "avatarAnalysisStatus": "analyzed", "estimatedAge": 34, "inferredGender": "female", "profileImageCategory": "individual_portrait", "hairColor": "black", "skinTone": "fair", "checkedAt": "2026-06-09T08:00:00Z" } ``` ### Output Fields | Field | Description | |-------|-------------| | `phoneNumber` | Normalized E.164 phone number. | | `originalInput` | Original value supplied by the user. | | `countryCode` | Detected country code. | | `isValidFormat` | Whether the number has a 7-15 digit format. | | `hasWhatsapp` | Whether the number has WhatsApp. | | `hasAvatar` | Whether an analyzable avatar URL was returned. | | `avatarUrl` | WhatsApp avatar image URL when available. | | `avatarAnalysisStatus` | `analyzed`, `no_avatar`, `not_on_whatsapp`, or `unknown`. | | `estimatedAge` | Inferred age from the profile image. | | `inferredGender` | `male`, `female`, `unknown`, or `null`. | | `profileImageCategory` | Inferred image category such as `individual_portrait`, `group_photo`, `cartoon_avatar`, or `object`. | | `hairColor` | Inferred hair color from the profile image. | | `skinTone` | Inferred skin color or tone from the profile image. | | `checkedAt` | ISO timestamp of analysis. | ### Pricing The actor uses pay-per-event pricing with one `profile_analyzed` event per analyzed number. Current planned rates per 1,000 analyzed numbers: | Plan | Price per 1,000 | |------|----------------:| | No subscription / Bronze | $9.00 / $7.50 | | Silver | $6.00 | | Gold and above | $4.50 | Duplicates are removed before analysis, so you pay for unique numbers analyzed. ### Notes - Rows without an analyzable profile image are mapped to `avatarAnalysisStatus = no_avatar`. - Unknown result values are normalized to `unknown` or `null`. - Uploaded CSV/XLSX files can use common phone columns such as `phone`, `mobile`, `telephone`, or `whatsapp`. - `onlyWhatsappUsers` filters output rows, but billing still applies to every analyzed number. # Actor input Schema ## `testMode` (type: `boolean`): Return sample records without analyzing real numbers or charging credits.

Disable this for real runs. ## `phoneNumbers` (type: `array`): Add phone numbers with country code, for example +14155552671.

Real runs require at least 100 unique numbers after duplicate removal. Oversized inputs are trimmed to the first 10,000 unique normalized numbers. ## `csvFile` (type: `string`): Upload a CSV or Excel .xlsx file containing phone numbers.

The actor detects common phone columns such as phone, mobile, telephone, and whatsapp. ## `defaultCountryCode` (type: `string`): Country code to prepend when a number does not start with +.

Examples: 1 for US/Canada, 44 for UK, 91 for India. ## `onlyWhatsappUsers` (type: `boolean`): Output only numbers where hasWhatsapp is true.

Billing still applies to every analyzed number. ## Actor input object example ```json { "testMode": true, "phoneNumbers": [ "+14155552671" ], "onlyWhatsappUsers": false } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "testMode": true, "phoneNumbers": [ "+14155552671" ] }; // Run the Actor and wait for it to finish const run = await client.actor("clearpath/whatsapp-profile-avatar-age-gender-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "testMode": True, "phoneNumbers": ["+14155552671"], } # Run the Actor and wait for it to finish run = client.actor("clearpath/whatsapp-profile-avatar-age-gender-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "testMode": true, "phoneNumbers": [ "+14155552671" ] }' | apify call clearpath/whatsapp-profile-avatar-age-gender-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=clearpath/whatsapp-profile-avatar-age-gender-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "WhatsApp Profile Avatar API - Age & Gender", "description": "Analyze WhatsApp phone numbers for profile avatar URL, WhatsApp presence, inferred age, gender, image category, hair color, and skin tone. Upload CSV/XLSX or paste numbers.", "version": "0.0", "x-build-id": "X0ePspTWDZM5Qd7r3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/clearpath~whatsapp-profile-avatar-age-gender-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-clearpath-whatsapp-profile-avatar-age-gender-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/clearpath~whatsapp-profile-avatar-age-gender-api/runs": { "post": { "operationId": "runs-sync-clearpath-whatsapp-profile-avatar-age-gender-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/clearpath~whatsapp-profile-avatar-age-gender-api/run-sync": { "post": { "operationId": "run-sync-clearpath-whatsapp-profile-avatar-age-gender-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "testMode": { "title": "Test Mode", "type": "boolean", "description": "Return sample records without analyzing real numbers or charging credits.

Disable this for real runs.", "default": false }, "phoneNumbers": { "title": "Phone Numbers", "minItems": 1, "maxItems": 10000, "type": "array", "description": "Add phone numbers with country code, for example +14155552671.

Real runs require at least 100 unique numbers after duplicate removal. Oversized inputs are trimmed to the first 10,000 unique normalized numbers.", "items": { "type": "string" } }, "csvFile": { "title": "CSV/Excel File", "type": "string", "description": "Upload a CSV or Excel .xlsx file containing phone numbers.

The actor detects common phone columns such as phone, mobile, telephone, and whatsapp." }, "defaultCountryCode": { "title": "Default Country Code", "type": "string", "description": "Country code to prepend when a number does not start with +.

Examples: 1 for US/Canada, 44 for UK, 91 for India." }, "onlyWhatsappUsers": { "title": "Only WhatsApp Users", "type": "boolean", "description": "Output only numbers where hasWhatsapp is true.

Billing still applies to every analyzed number.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```