> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # Profile object > Describes the contents of a profile record. This page describes the `profile` object, which represents a business's social media or third-party platform profile. Profiles are derived from websites or matched from web presence analysis. Possible profile types include Google Places, Facebook Pages, LinkedIn Profiles, Instagram Pages, Yelp Pages, Better Business Bureau (BBB) profiles, Trustpilot profiles, X profiles, and TikTok profiles. ## Retrieve profiles for a business You can retrieve the profiles associated with a business using the [Retrieve a business](/api-reference/business-verification/businesses/retrieve-a-business) endpoint. Profiles are included in the business response. ```bash curl https://api.middesk.com/v1/businesses/{business_id} \ -u {API_KEY}: ``` **`Example Google profile`** ```json title="Example Google profile" { "object": "profile", "type": "google", "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "external_id": "10000000000000000001", "url": "https://maps.google.com/?cid=10000000000000000001", "metadata": { "full_address": "123 Main St Suite 100, San Francisco, CA 94105", "name": "Acme Manufacturing", "website_urls": ["https://www.acmemanufacturing.com/"], "latitude": 37.78827, "longitude": -122.39997, "phone_number": "(415) 555-0100", "categories": ["Machine shop"], "reviews": [ { "rating": 5, "posted_at": "2024-03-15T14:30:00.000Z" } ] }, "rating": 5, "rating_count": 1 } ``` **`Example Facebook profile`** ```json title="Example Facebook profile" { "object": "profile", "type": "facebook", "id": "b2c3d4e5-6789-01ab-cdef-2345678901ab", "external_id": null, "url": "https://facebook.com/acme-manufacturing", "metadata": { "city": "San Francisco", "state": "CA", "name": "Acme Manufacturing", "recent_posts": [], "recent_reviews": [] }, "rating": null, "rating_count": null } ``` **`Example BBB profile`** ```json title="Example BBB profile" { "object": "profile", "type": "bbb", "id": "c3d4e5f6-7890-12ab-cdef-3456789012ab", "external_id": null, "url": "https://www.bbb.org/us/ca/san-francisco/profile/manufacturing/acme-manufacturing-1111-123456789", "metadata": { "external_id": "123456789", "name": "Acme Manufacturing", "bbb_rating": "A+", "is_accredited": true, "review_count": 12, "average_review_rating": 4.5 }, "rating": 4.5, "rating_count": 12 } ``` ## Profile attributes | Attribute | Type | Description | | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | string | The object type. Always `profile`. | | `id` | string (uuid) | The unique identifier for the profile record. | | `type` | string | Type of profile. Valid values are `facebook`, `google`, `instagram`, `linkedin`, `yelp`, `bbb`, `trustpilot`, `x`, and `tiktok`. | | `external_id` | string \| null | Third-party identifier for the profile. Only populated for Google Places profiles; for BBB, X, and TikTok the platform identifier is in `metadata.external_id` instead. | | `url` | string | Canonical URL for the profile. | | `status` | string | Status of the profile. Valid values are `online`, `offline`, and `unknown`. | | `submitted` | boolean | Indicates whether the profile was submitted by the user (`true`) or discovered by Middesk (`false`). | | `error` | string \| null | Error message if there were issues fetching or processing the profile. | | `metadata` | object | Additional metadata sourced from the profile. See [Metadata structure](#metadata-structure) for details. | | `rating` | number \| null | Aggregate rating from the profile platform. For BBB, this is the average review star rating. For Trustpilot, this is the TrustScore. X and TikTok profiles do not have ratings and return `null`. | | `rating_count` | number \| null | Total number of ratings on the profile. For BBB and Trustpilot, this is the total review count. X and TikTok profiles return `null`. | ## Profile status values | Status | Description | | --------- | ------------------------------------------------------ | | `online` | The profile is accessible and responding normally. | | `offline` | The profile could not be reached or is not responding. | | `unknown` | The profile status could not be determined. | ## Metadata structure The `metadata` object contains profile-specific information that varies by profile type. Middesk omits fields with `null` values, so the fields below appear only when available. ### Google Places metadata | Attribute | Type | Description | | -------------- | --------- | ------------------------------------------------------ | | `name` | string | Business name. | | `full_address` | string | Full formatted address. | | `phone_number` | string | Phone number. | | `website_urls` | string\[] | Website URLs associated with the business. | | `latitude` | number | Geographic latitude. | | `longitude` | number | Geographic longitude. | | `categories` | string\[] | Array of business categories. | | `reviews` | object\[] | Array of review objects with `rating` and `posted_at`. | ### Facebook metadata | Attribute | Type | Description | | ---------------- | --------- | ------------------------------- | | `name` | string | Page name. | | `city` | string | City from the page's location. | | `state` | string | State from the page's location. | | `recent_posts` | object\[] | Array of recent post objects. | | `recent_reviews` | object\[] | Array of recent review objects. | ### Yelp metadata | Attribute | Type | Description | | ------------- | --------- | --------------------------------------------------- | | `name` | string | Business name. | | `price_range` | string | Price level indicator. | | `is_closed` | boolean | Whether the business is closed. | | `is_claimed` | boolean | Whether the business owner has claimed the listing. | | `reviews` | object\[] | Array of review objects. | ### BBB metadata | Attribute | Type | Description | | ---------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `external_id` | string | BBB business identifier. | | `name` | string | Business name on the BBB profile. | | `alternate_names` | string\[] | Alternate business names listed on the profile. | | `website` | string | Website URL listed on the profile. | | `profile_url` | string | Canonical BBB profile URL reported by BBB. May differ from the top-level `url`, which is the URL Middesk discovered or the customer submitted. | | `bbb_rating` | string | BBB letter grade (for example, `A+`). Omitted when the business is not rated. | | `rating_reasons` | string\[] | Reasons BBB cites for the rating. | | `is_accredited` | boolean | Whether the business is BBB accredited. | | `review_count` | number | Total number of customer reviews. | | `average_review_rating` | number | Average customer review star rating. | | `complaints_total` | number | Total complaints filed with BBB. | | `complaints_closed_past_3_years` | number | Complaints closed in the past three years. | | `complaints_closed_past_12_months` | number | Complaints closed in the past 12 months. | | `recent_reviews` | object\[] | Recent customer reviews, each with `display_name` and `preview_text`. | | `address` | object | Address on the profile, with `address_line1`, `address_line2`, `city`, `state`, and `zip`. | | `formatted_address` | string | Full formatted address. | | `contact_info` | object | Contact details, with `phone` (E.164) and `emails` (string\[]). | | `business_started_at` | string | Date the business started. | | `bbb_file_opened_at` | string | Date BBB opened its file on the business. | | `categories` | string\[] | Business categories listed on the profile. | | `primary_category` | string | Primary business category. | ### Trustpilot metadata | Attribute | Type | Description | | ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `name` | string | Business name on the Trustpilot profile. | | `domain` | string | Trustpilot identifying domain for the business. | | `trust_score` | number | Trustpilot TrustScore. | | `stars` | number | Star rating shown on the profile. | | `rating_count` | number | Total number of reviews. | | `rating_count_last_12_months` | number | Reviews posted in the past 12 months. | | `negative_reviews_count` | number | Number of negative reviews. | | `is_claimed` | boolean | Whether the business has claimed the profile. | | `is_closed` | boolean | Whether the business is listed as closed or temporarily closed. | | `categories` | object\[] | Categories, each with `id`, `name`, and `primary`. | | `website` | string | Website URL listed on the profile. | | `contact_info` | object | Contact details, with `email`, `phone`, `address`, `city`, `zip_code`, and `country`. | | `recent_reviews` | object\[] | Recent reviews, newest first, each with `rating`, `title`, `text`, `posted_at`, `experienced_at`, and `reply`. | | `first_review_at` | string | Date of the oldest review on the first page of reviews. | ### X metadata The profile `type` for X profiles is `x`. | Attribute | Type | Description | | ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------- | | `external_id` | string | X account identifier. | | `handle` | string | Account handle. | | `name` | string | Display name. | | `website` | string | Website URL listed on the profile. | | `description` | string | Profile bio. | | `location` | string | Location listed on the profile. | | `verified` | boolean | Whether the account is verified. | | `protected` | boolean | Whether the account is protected. | | `followers` | number | Follower count. | | `following` | number | Number of accounts the profile follows. | | `statuses_count` | number | Number of posts. | | `media_count` | number | Number of media items posted. | | `created_at` | string | When the account was created. | | `avatar` | string | URL of the profile image. | | `header_image` | string | URL of the header image. | | `recent_tweets` | object\[] | Recent posts, each with `tweet_id`, `created_at`, `text`, `views`, `favorites`, `retweets`, `replies`, and `entities`. | ### TikTok metadata | Attribute | Type | Description | | ------------- | ------- | ---------------------------------------- | | `external_id` | string | TikTok account identifier. | | `handle` | string | Account handle. | | `name` | string | Display name. | | `website` | string | Website URL listed on the profile. | | `description` | string | Profile bio. | | `verified` | boolean | Whether the account is verified. | | `protected` | boolean | Whether the account is private. | | `category` | string | Account category listed on the profile. | | `created_at` | string | When the account was created. | | `followers` | number | Follower count. | | `likes` | number | Total likes across the account's videos. | | `videos` | number | Number of videos posted. | ### LinkedIn and Instagram metadata Metadata structure varies based on the profile type and available information. > **Get a demo** > > Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.