Profile object | Middesk

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 endpoint. Profiles are included in the business response.

$ curl https://api.middesk.com/v1/businesses/{business_id} \
>   -u {API_KEY}:

Example Google profile

1 {
2   "object": "profile",
3   "type": "google",
4   "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
5   "external_id": "10000000000000000001",
6   "url": "https://maps.google.com/?cid=10000000000000000001",
7   "metadata": {
8     "full_address": "123 Main St Suite 100, San Francisco, CA 94105",
9     "name": "Acme Manufacturing",
10     "website_urls": ["https://www.acmemanufacturing.com/"],
11     "latitude": 37.78827,
12     "longitude": -122.39997,
13     "phone_number": "(415) 555-0100",
14     "categories": ["Machine shop"],
15     "reviews": [
16       {
17         "rating": 5,
18         "posted_at": "2024-03-15T14:30:00.000Z"
19       }
20     ]
21   },
22   "rating": 5,
23   "rating_count": 1
24 }

Example Facebook profile

1 {
2   "object": "profile",
3   "type": "facebook",
4   "id": "b2c3d4e5-6789-01ab-cdef-2345678901ab",
5   "external_id": null,
6   "url": "https://facebook.com/acme-manufacturing",
7   "metadata": {
8     "city": "San Francisco",
9     "state": "CA",
10     "name": "Acme Manufacturing",
11     "recent_posts": [],
12     "recent_reviews": []
13   },
14   "rating": null,
15   "rating_count": null
16 }

Example BBB profile

1 {
2   "object": "profile",
3   "type": "bbb",
4   "id": "c3d4e5f6-7890-12ab-cdef-3456789012ab",
5   "external_id": null,
6   "url": "https://www.bbb.org/us/ca/san-francisco/profile/manufacturing/acme-manufacturing-1111-123456789",
7   "metadata": {
8     "external_id": "123456789",
9     "name": "Acme Manufacturing",
10     "bbb_rating": "A+",
11     "is_accredited": true,
12     "review_count": 12,
13     "average_review_rating": 4.5
14   },
15   "rating": 4.5,
16   "rating_count": 12
17 }

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 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 to inquire about access.