SocialCrawl Trustpilot API

openapi: 3.2.0
info:
  title: SocialCrawl Trustpilot API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: trustpilot
  description: Trustpilot endpoints
paths:
  /trustpilot/business-search:
    get:
      summary: Search Trustpilot businesses
      description: 'Searches Trustpilot for businesses (companies) matching a keyword. Returns a unified AuthorList: each result is a business profile with its display name, Trustpilot domain (`username`/`id`), own website (`external_url`), Trustpilot review-page URL (`url`), and total Trustpilot review count (`posts_count`). Use the returned domain to pull that business''s reviews via /v1/trustpilot/reviews. Note: search matches BUSINESSES, not products: a domain-shaped query returns no results. Sourced from DataForSEO''s task-based Business Data API; the async lifecycle is handled server-side, so this is an ordinary synchronous request (first calls take ~15-45s, then serve from cache).'
      tags:
      - trustpilot
      operationId: get_trustpilot_business_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: query
        in: query
        required: true
        description: Business name or keyword (e.g. 'nike'). Matches companies, not products; do not pass a bare domain.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of business results to retrieve (default 20, multiples of 10, max 140). More results = longer task time.
        schema:
          type: integer
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical author wrappers ({ author })
                        items:
                          type: object
                          description: Canonical author wrapper
                          properties:
                            author:
                              type: object
                              description: Canonical Author object (unified across all platforms)
                              properties:
                                id:
                                  type: string
                                  description: Platform-specific user ID (always a string; platform-specific prefixes like `did:`, `spotify:artist:`, `t2_` are stripped)
                                username:
                                  type:
                                  - string
                                  - 'null'
                                  description: User handle or username
                                display_name:
                                  type:
                                  - string
                                  - 'null'
                                  description: Display name or full name
                                avatar_url:
                                  type:
                                  - string
                                  - 'null'
                                  description: URL to profile picture
                                bio:
                                  type:
                                  - string
                                  - 'null'
                                  description: Profile biography or description
                                verified:
                                  type:
                                  - boolean
                                  - 'null'
                                  description: Whether the account is verified
                                followers:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Follower or subscriber count as an integer. Exact on Instagram and on TikTok when the source exposes an unrounded figure. YouTube above 1,000 subscribers is YouTube's published three-significant-figure figure. When the integer is a published/rounded value, `author.ext.followers_approximate` is true.
                                following:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Number of accounts followed
                                posts_count:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Total number of posts / videos / tracks / episodes
                                likes_count:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Total likes received across the author's content (when surfaced)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Direct URL to the profile page
                                location:
                                  type:
                                  - string
                                  - 'null'
                                  description: ISO region code (e.g. `US`) or freeform location string when surfaced
                                external_url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Bio link / external website URL when surfaced by the platform
                                private:
                                  type:
                                  - boolean
                                  - 'null'
                                  description: Boolean at author.private
                                joined_at:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at author.joined_at
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: 'Nested object: author.ext'
                                  properties:
                                    social_context:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.social_context
                                    account_created:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.account_created
                                    country:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.country
                                    former_usernames:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.former_usernames
                                      items:
                                        type: string
                                        description: String at author.ext.former_usernames
                                    public_email:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.public_email
                                    public_phone:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.public_phone
                                    business_category:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.business_category
                                    hd_avatar_url:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.hd_avatar_url
                                    website:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.website
                                    cover_url:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.cover_url
                                    page_active:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.page_active
                                    employee_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.employee_count
                                    employee_count_range:
                                      type:
                                      - object
                                      - 'null'
                                      description: 'Nested object: author.ext.employee_count_range'
                                      properties:
                                        start:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at author.ext.employee_count_range.start
                                        end:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at author.ext.employee_count_range.end
                                    founded_year:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.founded_year
                                    specialities:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.specialities
                                      items:
                                        type: string
                                        description: String at author.ext.specialities
                                    industries:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.industries
                                      items:
                                        type: string
                                        description: String at author.ext.industries
                                    headquarters:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at author.ext.headquarters
                                    locations:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.locations
                                      items:
                                        type: string
                                        description: Leaf at author.ext.locations
                                    hashtags:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.hashtags
                                      items:
                                        type: string
                                        description: Leaf at author.ext.hashtags
                                    funding:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at author.ext.funding
                                    address:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.address
                                    price_range:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.price_range
                                    rating:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.rating
                                    rating_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.rating_count
                                    talking_about_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.talking_about_count
                                    business_hours:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.business_hours
                                      items:
                                        type: string
                                        description: Leaf at author.ext.business_hours
                                    links:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.links
                                      items:
                                        type: string
                                        description: Leaf at author.ext.links
                                    ad_library_page_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.ad_library_page_id
                                    ad_library_status:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.ad_library_status
                                    urn:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.urn
                                    is_top_voice:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.is_top_voice
                                    is_premium:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.is_premium
                                    followers_approximate:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: 'True when `author.followers` is a published or rounded figure rather than an unrounded census: LinkedIn people-list display buckets, TikTok `stats.followerCount` when the exact sibling is absent, and YouTube subscriber counts at or above 1,000. Null or absent on exact counts.'
                                    keywords:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.keywords
                                    topicCategories:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.topicCategories
                                      items:
                                        type: string
                                        description: String at author.ext.topicCategories
                                    bannerExternalUrl:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.bannerExternalUrl
                                    madeForKids:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.madeForKids
                                    hiddenSubscriberCount:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.hiddenSubscriberCount
                                    related_playlists:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at author.ext.related_playlists
                                    topic_ids:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at author.ext.topic_ids
                                      items:
                                        type: string
                                        description: String at author.ext.topic_ids
                                    unsubscribed_trailer:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.unsubscribed_trailer
                                    monthly_listeners:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.monthly_listeners
                                    total_ratings:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'Spotify podcasts only: how many listeners have rated the show. Cumulative over the show''s whole run, so it reflects longevity as well as size, and it is NOT an audience count (Spotify publishes no play, download, subscriber or follower count for a podcast)'
                                    average_rating:
                                      type:
                                      - integer
                                      - 'null'
                                      description: 'Spotify podcasts only: mean listener rating from 0 to 5. Fractional (e.g. 4.66) despite the integer type this schema emits for every numeric leaf'
                                    creator_username:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.creator_username
                                    join_policy:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.join_policy
                                    is_nsfw:
                                      type:
                                      - boolean
                                      - 'null'
                                      description: Boolean at author.ext.is_nsfw
                                    weekly_active_users:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.weekly_active_users
                                    weekly_contributions:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at author.ext.weekly_contributions
                                    bio_link:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at author.ext.bio_link
                                    group:
                                      type:
                                      - string
                                      - 'null'
                                      description: Leaf at author.ext.group
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /trustpilot/reviews:
    get:
      summary: Get Trustpilot reviews for a business
      description: 'Returns a unified ReviewList of customer reviews for a business on Trustpilot, keyed by its domain (`entity_id` on every review). Each review carries the star rating, full text, title, verified-status, language (reviews arrive in many languages: filter client-side via `language`), reviewer profile, owner/brand `responses[]`, and publish date. Reviews are about the COMPANY (shipping, refunds, support), never a specific product: for product reviews use /v1/google_shopping/reviews or /v1/amazon/reviews. Get the domain from /v1/trustpilot/business-search. The platform exposes no deeper pagination: `depth` caps at 200 (the most recent / most relevant); a business with no Trustpilot reviews returns 404 (auto-refunded). Sourced from DataForSEO''s task-based Business Data API (first calls ~15-45s, then cached).'
      tags:
      - trustpilot
      operationId: get_trustpilot_reviews
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: domain
        in: query
        required: true
        description: The business's domain on Trustpilot (e.g. 'www.nike.com' or 'booking.com'), from business-search.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of reviews to retrieve (default 20, multiples of 20, max 200). There is no pagination beyond 200.
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Review ordering: `recency` (newest first, default) or `relevance`.'
        schema:
          type: string
          enum:
          - recency
          - relevance
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        requi

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-trustpilot-api-openapi.yml