CreatorIQ Social API

openapi: 3.2.0
info:
  version: 1.0.0
  title: CreatorIQ Account Social API
  description: "CreatorIQ CRM APIs for Social Account resource\n### Changelog\n\n#### 2025-02-27\n\n#### Added\n\n- new value `savedThumbnail` for YouTube video item for endpoint:\nGET [https://apis.creatoriq.com/crm/v1/api/social/postInfo YouTube video only](https://creatoriq.stoplight.io/docs/ciq-api-documentation/f575c27239d31-get-social-post-info)\n\n\n#### 2025-01-22\n\n#### Added\n\n- Added new value `pnkHash` for social post item for endpoints:\n  - [GET https://apis.creatoriq.com/crm/v1/api/social/postInfo](https://creatoriq.stoplight.io/docs/ciq-api-documentation/f575c27239d31-get-social-post-info)\n  - [GET https://apis.creatoriq.com/crm/v1/api/account/instagram/{id}/storiesHistory](https://creatoriq.stoplight.io/docs/ciq-api-documentation/d83baf3f82db6-get-stories-history)\n"
  termsOfService: https://www.creatoriq.com/legal/terms-of-use
  contact:
    name: CreatorIQ
    url: https://www.creatoriq.com
    email: support@creatoriq.com
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://apis.creatoriq.com
  description: Live
security:
- apiKey: []
tags:
- name: Social
  description: Public social API
paths:
  /crm/v1/api/account/instagram/{id}/storiesHistory:
    get:
      tags:
      - Social
      summary: Get stories history
      description: "## Fetch stories history for Instagram social account\nThe endpoint returns the entire history starting from the moment when the creator's social account was linked\nand story monitoring was enabled. \nFor example, the curl below (without parameters) will return the entire Instagram stories history:\n\n```\ncurl -X GET --location \"https://apis.creatoriq.com/crm/v1/api/account/instagram/changedtokrakow/storiesHistory\" \\\n-H \"X-API-KEY: apikey\" \\\n-H \"Content-Type: application/json\"\n``` \n\n\n\nHowever, if we want to retrieve stories for a \nspecific period (in days), we set the exact dates of the period using the parameters ```from``` and ```to```. The format of \nthe ```from``` and ```to``` fields is ```YYYY-MM-DD```. The maximum number of entities obtained per request can be regulated by \nthe ```size``` parameter.\nFor example:\n```\ncurl -X GET --location \"https://apis.creatoriq.com/crm/v1/api/account/instagram/changedtokrakow/storiesHistory?from=2022-06-20&to=2022-06-23&size=2\" \\\n    -H \"X-API-KEY: apikey\" \\\n    -H \"Content-Type: application/json\"\n```\n"
      operationId: getInstagramStoriesHistory
      parameters:
      - name: from
        in: query
        description: From what date fetch stories
        required: false
        schema:
          type: string
          format: date
          example: '2022-09-13'
        examples:
          default:
            value: '2022-09-13'
      - name: size
        in: query
        description: Count of fetched
        required: false
        schema:
          type: integer
          example: 20
        examples:
          default:
            value: 20
      - name: to
        in: query
        description: From date fetch
        required: false
        schema:
          type: string
          format: date
          example: '2022-09-13'
        examples:
          default:
            value: '2022-09-13'
      - name: id
        in: path
        description: Instagram unique Identifier or username
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_\.]+$
          example: melrosehealth
        examples:
          default:
            value: melrosehealth
      responses:
        '200':
          $ref: '#/components/responses/InstagramAccountStoriesSuccessResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
  /crm/v1/api/social/accountInfo:
    get:
      tags:
      - Social
      summary: Get social account data
      description: 'Returns information about a specific social account using either a social account url or a combination of the social network and username. <br/>

        Allowed social networks: tiktok, instagram, twitch, youtube, facebook.

        '
      operationId: getSocialAccountData
      parameters:
      - name: source
        in: query
        description: Account data source (can be 'link' or 'user')
        required: true
        schema:
          type: string
          enum:
          - link
          - user
          example: link
        examples:
          default:
            value: link
      - name: link
        in: query
        description: link to user social media account. Required if `source=link`
        required: false
        schema:
          type: string
          example: https:\\www.tiktok.com\@therock
        examples:
          default:
            value: https:\\www.tiktok.com\@therock
      - name: network
        in: query
        description: Name os social network. Required if `source=user`
        required: false
        schema:
          type: string
          enum:
          - tiktok
          - instagram
          - twitch
          - youtube
          - facebook
          example: youtube
        examples:
          default:
            value: youtube
      - name: user
        in: query
        description: Username or user id on social media. Requred if `source=user`
        required: false
        schema:
          type: string
          example: therock
        examples:
          default:
            value: therock
      responses:
        '200':
          description: One of possible responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InstagramAccountInfoModel'
                - $ref: '#/components/schemas/YoutubeAccountInfoModel'
                - $ref: '#/components/schemas/FacebookAccountInfoModel'
                - $ref: '#/components/schemas/TiktokAccountInfoModel'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
  /crm/v1/api/social/postInfo:
    get:
      tags:
      - Social
      summary: Get Social PostInfo
      description: Returns information about a specific social media post
      operationId: getSocialPostInfo
      parameters:
      - name: link
        in: query
        description: Url to specific social network post
        required: true
        schema:
          type: string
          example: https://www.instagram.com/p/Cm-qszQrIla
        examples:
          default:
            value: https://www.instagram.com/p/Cm-qszQrIla
      - name: publisherId
        in: query
        description: Unique publisher id. Required if `checkAccounts=1`
        required: false
        schema:
          type: integer
          example: 841602
        examples:
          default:
            value: 841602
      - name: checkAccounts
        in: query
        description: Check if account exists in database
        required: false
        schema:
          type: integer
          enum:
          - 0
          - 1
          example: 0
        examples:
          default:
            value: 0
      responses:
        '200':
          description: One of possible responses
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/InstagramPostModel'
                - $ref: '#/components/schemas/FacebookPostModel'
                - $ref: '#/components/schemas/LinkedinPostModel'
                - $ref: '#/components/schemas/PinterestPostModel'
                - $ref: '#/components/schemas/SnapchatPostModel'
                - $ref: '#/components/schemas/TiktokPostModel'
                - $ref: '#/components/schemas/TwitchPostModel'
                - $ref: '#/components/schemas/TwitterPostModel'
                - $ref: '#/components/schemas/WebPostModel'
                - $ref: '#/components/schemas/YoutubePostModel'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
  /crm/v1/api/accounts/lookup:
    get:
      tags:
      - Social
      summary: Search user in social network or in the CreatorIQ database
      description: Search Creator by Social handle within your CRM
      operationId: getUserInSocialNetwork
      parameters:
      - name: network
        in: query
        description: Name of social network.
        required: true
        schema:
          type: string
          enum:
          - tiktok
          - twitter
          - pinterest
          - instagram
          - youtube
          - twitch
          - facebook
          example: youtube
        examples:
          default:
            value: youtube
      - name: search
        in: query
        description: Search string or username or link to social account
        required: true
        schema:
          type: string
          example: therock
        examples:
          default:
            value: therock
      responses:
        '200':
          $ref: '#/components/responses/LookupSuccessResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
  /crm/v1/api/{network}/account/{socialNetworkId}/history:
    get:
      tags:
      - Social
      summary: Get social account history
      description: "### Get social account history\nThis endpoint returns the subscription and viewing history of a social account for the period that we set in \nthe parameters. The period can be set in days or months using the parameter ```period=month``` or ```period=day```. \nHowever, the endpoint will not return the account history for 12 months if the database only stores history \nfor 6 months. \n\n\nIf the period field is set to ```period=day```, the endpoint will return the history of changes in \nviews or subscriptions for the dates when the CreatorIQ cron recorded changes in the number of views or \nsubscribers. For example, if the account had 4 subscribers and 0 views on September 1, 2022, and the \naccount was added to CreatorIQ on the same day - September 1, 2022, and 49 views were added on October 1, 2022, \nthe output will be:\n```\n  {\n    \"SocialHistory\":[\n      {\n        \"Date\":\"2022-10-01 00:00:00\",\n        \"Subscribers\":\"4\",\n        \"Views\":\"49\"\n      },\n      {\n        \"Date\":\"2022-09-01 00:00:00\",\n        \"Subscribers\":\"4\",\n        \"Views\":\"0\"\n      }\n    ],\n    \"href\":\"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCJ80aAk5PcrD_bEYscCRkpQ/history?period=day&size=2\",\n    \"type\":\"SocialHistory\"\n}\n``` \nAs we can see, the data is returned starting from the oldest date. \nInput curl was:\n```\ncurl -X GET --location \"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCJ80aAk5PcrD_bEYscCRkpQ/history?period=day&size=2\" \\\n-H \"X-API-KEY: apikey\" \\\n-H \"Content-Type: application/json\"\n```\n\n\nIf ```period=month```, the history of changes in the number of subscribers or views of the social account is returned \nby months. For example:\n```\n{\n   \"SocialHistory\":[\n      {\n         \"Month\":\"December 2022\",\n         \"Subscribers\":\"2050000\",\n         \"Views\":228074626\n      },\n      {\n         \"Month\":\"January 2023\",\n         \"Subscribers\":\"2770000\",\n         \"Views\":214931823.33333\n      },\n      {\n         \"Month\":\"February 2023\",\n         \"Subscribers\":\"2993334\",\n         \"Views\":81111695.5\n      }\n   ],\n   \"href\":\"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCd84KUlhKQYXrMHsOPfyxcw/history?period=month&size=40\",\n   \"type\":\"SocialHistory\"\n}\n``` \nThe data is returned starting from the most recent date.\nInput curl was:\n```\ncurl -X GET --location \"https://apis.creatoriq.com/crm/v1/api/youtube/account/UCd84KUlhKQYXrMHsOPfyxcw/history?period=month&size=40\" \\\n-H \"X-API-KEY: apikey\" \\\n-H \"Content-Type: application/json\"\n```\n\nUsing the ```size``` parameter, we can regulate the maximum number of entities in the response.\n"
      operationId: getSocialAccountHistory
      parameters:
      - name: period
        in: query
        description: Period which history fetch
        required: false
        schema:
          type: string
          enum:
          - month
          - day
          default: day
          example: month
        examples:
          default:
            value: month
      - name: size
        in: query
        description: Count
        required: false
        schema:
          type: integer
          minimum: 0
          example: 6
        examples:
          default:
            value: 6
      - name: network
        in: path
        description: Social network
        required: true
        schema:
          type: string
          enum:
          - youtube
          - twitch
          - instagram
          - facebook
          - twitter
          - pinterest
          example: facebook
        examples:
          default:
            value: facebook
      - name: socialNetworkId
        in: path
        description: 'Unique id of account from network. Can be fetched from [GET] ''/crm/v1/api/publisher/{publisherId}/accounts'' endpoint.

          Field in response **SocialNetworkId**

          '
        required: true
        schema:
          type: string
          example: '2094200507'
        examples:
          default:
            value: '2094200507'
      responses:
        '200':
          $ref: '#/components/responses/socialHistory'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
      security:
      - apiKey: []
      servers:
      - url: https://apis.creatoriq.com
        description: Live
components:
  schemas:
    LookupSuccessResponseModel:
      type: object
      properties:
        type:
          type: string
          description: Type of Search
          example: LookupResult
        href:
          type: string
          description: CreatorIQ API URL to get creator's account lookup
          format: URI
          example: https://apis.creatoriq.com/crm/v1/api/accounts/lookup?network=instagram&search=%22https%3A%2F%2Fwww.instagram.com%2Ftherock%2F%22
        LookupResult:
          type: object
          properties:
            existsInDatabase:
              type: boolean
              example: true
            data:
              type: object
              properties:
                Id:
                  type: integer
                  description: Unique publisher id
                  format: int32
                  example: 12472164
                PublisherName:
                  type: string
                  description: Publisher name
                  example: The Rock
                LegalGuardian:
                  type:
                  - string
                  - 'null'
                  example: null
                OutsideManagerName:
                  type:
                  - string
                  - 'null'
                  example: null
                ManagementCompany:
                  type:
                  - string
                  - 'null'
                  example: null
                NetworkPublisherId:
                  type: string
                  example: '10011233269'
                InvitedToPortal:
                  type: integer
                  format: int32
                  example: 0
                LogoURL:
                  type: string
                  description: Url to social network account logo
                  format: URI
                  example: https://social-pictures-storage.s3.us-west-1.amazonaws.com/Logo/therock_instagram_Logo.jpg
                PrimaryContactId:
                  type: integer
                  format: int32
                  example: 117093285
                ShipToContactId:
                  type:
                  - string
                  - 'null'
                  example: null
                FinanceContactId:
                  type:
                  - string
                  - 'null'
                  example: null
                OutsideManagerContactId:
                  type:
                  - string
                  - 'null'
                  example: null
                LegalGuardianContactId:
                  type:
                  - string
                  - 'null'
                  example: null
                DateOfBirth:
                  type:
                  - string
                  - 'null'
                  example: null
                GeoRegionId:
                  type:
                  - string
                  - 'null'
                  example: null
                Language:
                  type: string
                  description: Language
                  example: English
                Language2:
                  type:
                  - string
                  - 'null'
                  example: null
                EthnicBackground:
                  type:
                  - string
                  - 'null'
                  example: null
                AgeRange:
                  type:
                  - string
                  - 'null'
                  example: null
                Gender:
                  type: string
                  enum:
                  - Male
                  - Female
                  description: Gender
                  example: Male
                RecruiterName:
                  type: string
                  example: Test User
                AccountManagerName:
                  type:
                  - string
                  - 'null'
                  example: null
                NetworkId:
                  type: integer
                  description: Network id
                  format: int32
                  example: 21
                NetworkName:
                  type: string
                  description: Network name
                  example: Test
                SubNetworkId:
                  type:
                  - string
                  - 'null'
                  example: null
                SubNetworkName:
                  type:
                  - string
                  - 'null'
                  example: null
                FlagshipProperty:
                  type: string
                  example: therock
                NumberOfChannels:
                  type:
                  - string
                  - 'null'
                  example: null
                ChannelList:
                  type:
                  - string
                  - 'null'
                  example: null
                Category:
                  type:
                  - string
                  - 'null'
                  example: null
                PublisherType:
                  type:
                  - string
                  - 'null'
                  example: null
                BrandsWishes:
                  type:
                  - string
                  - 'null'
                  example: null
                BrandsContracts:
                  type:
                  - string
                  - 'null'
                  example: null
                PressList:
                  type:
                  - string
                  - 'null'
                  example: null
                SubCategories:
                  type:
                  - string
                  - 'null'
                  example: null
                CRMOpportunityId:
                  type:
                  - string
                  - 'null'
                  example: null
                CRMOpportunityName:
                  type:
                  - string
                  - 'null'
                  example: null
                CRMOpportunityState:
                  type:
                  - string
                  - 'null'
                  example: null
                Size:
                  type:
                  - string
                  - 'null'
                  example: null
                PublisherState:
                  type: string
                  example: Active
                PublisherStateChangeReason:
                  type: string
                  example: In Network
                PipelineId:
                  type:
                  - string
                  - 'null'
                  example: null
                Pipeline:
                  type: string
                  example: RecruitingOutreach
                PipelineStage:
                  type:
                  - string
                  - 'null'
                  example: null
                PipelineStageChangeReason:
                  type:
                  - string
                  - 'null'
                  example: null
                ExpectedCloseDate:
                  type:
                  - string
                  - 'null'
                  example: null
                Probability:
                  type:
                  - string
                  - 'null'
                  example: null
                LeadSource:
                  type: string
                  example: Broad Search
                ContractSummary:
                  type:
                  - string
                  - 'null'
                  example: null
                DatedClaimed:
                  type:
                  - string
                  - 'null'
                  example: null
                DateInvited:
                  type:
                  - string
                  - 'null'
                  example: null
                DateWelcomeEmailSent:
                  type:
                  - string
                  - 'null'
                  example: null
                DateRecruitingStarted:
                  type: string
                  description: The date when creator was added to CRM
                  format: date-time
                  example: '2022-10-25 15:52:28'
                DateFirstContractSigned:
                  type:
                  - string
                  - 'null'
                  example: null
                DateFirstChannelActivated:
                  type:
                  - string
                  - 'null'
                  example: null
                MonthFirstChannelActivated:
                  type:
                  - string
                  - 'null'
                  example: null
                DateFirstNetworkVideoViews:
                  type:
                  - string
                  - 'null'
                  example: null
                MonthFirstNetworkVideoViews:
                  type:
                  - string
                  - 'null'
                  example: null
                DateJoinedNetwork:
                  type:
                  - string
                  - 'null'
                  description: The date when creator was activated, i.e. status changed to active (seems unused now)
                  example: null
                DateLastContact:
                  type:
                  - string
                  - 'null'
                  example: null
                DatePublisherStateChanged:
                  type: string
                  format: date
                  example: '2023-01-05'
                DatePipelineStageChanged:
                  type:
                  - string
                  - 'null'
                  example: null
                DateJoinedPublisherPortal:
                  type:
                  - string
                  - 'null'
                  example: null
                DateLastPublisherPortalLogin:
                  type:
                  - string
                  - 'null'
                  example: null
                Description:
                  type: string
                  example: Some description here
                CustomTag1:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomTag2:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomTag3:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomField1:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomValue1:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomField2:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomValue2:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomField3:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomValue3:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomField4:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomValue4:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomField5:
                  type:
                  - string
                  - 'null'
                  example: null
                CustomValue5:
                  type:
                  - string
                  - 'null'
                  example: null
                LastUpdated:
                  type: string
                  description: Last update date
                  format: date-time
                  example: '2023-01-11 08:44:06'
                UpdatedBy:
                  type: string
                  description: Person who update data
                  example: Test User
                HasAdSense:
                  type: integer
                  format: int32
                  example: 0
                AdSenseDisabled:
                  type: integer
                  format: int32
                  example: 0
                AdSenseIssue:
                  type:
                  - string
                  - 'null'
                  example: null
                OtherNetwork:
                  type:
                  - string
                  - 'null'
                  example: null
                AllowReApply:
                  type:
                  - string
                  - 'null'
                  example: null
                RegistrationCompleted:
                  type: integer
                  format: int32
                  example: 0
                DatePublisherActivated:
                  type: string
                  description: Publisher activated date
                  format: date
                  example: '2023-01-05'
                DatePublisherDeActivated:
                  type:
                  - string
                  - 'null'
                  example: null
                Relationship:
                  type:
                  - string
                  - 'null'
                  example: null
                InternalDescription:
                  type:
                  - string
                  - 'null'
                  example: null
                ShortDescription:
                  type:
                  - string
                  - 'null'
                  example: null
                Children:
                  type:
                  - string
                  - 'null'
                  example: null
                Pets:
                  type:
                  - string
                  - 'null'
                  example: null
                Car:
                  type:
                  - string
                  - 'null'
                  example: null
                LogoHighResURL:
                  type: string
                  description: Url to profile logo
                  format: URI
                  example: https://social-pictures-storage.s3.us-west-1.amazonaws.com/Logo/therock_instagram_Logo.jpg
                Tags:
                  type:
                  - string
                  - 'null'
                  example: null
                InterfaceLocale:
                  type:
                  - string
                  - 'null'
                  example: null
                FlagshipSocialNetwork:
                  type: string
                  example: instagram
                TalentAgency:
                  type:
                  - string
                  - 'null'
                  example: null
                Unsubscribe:
                  type: integer
                  format: int32
                  example: 0
                DontContact:
                  type: integer
                  format: int32
                  example: 0
                WillTravel:
                  type:
                  - string
                  - 'null'
                  example: null
                ContentRating:
                  type:
                  - string
                  - 'null'
                  example: null
                ContactPreference:
                  type:
                  - string
                  - 'null'
                  example: null
                TermsAccepted:
                  type:
                  - string
                  - 'null'
                  example: null
                DateTermsAccepted:
                  type:
                  - string
                  - 'null'
                  example: null
                BrandsWontWork:
                  type: string
                  example: Array
                BrandsWorked:
                  type:
                  - string
                  - 'null'
                  example: null
                BrandsWishWork:
                  type:
                  - string
                  - 'null'
                  example: null
                Glasses:
                  type:
                  - string
                  - 'null'
                  example: null
                EyeColor:
                  type:
                  - string
                  - 'null'
                  example: null
                HairColor:
                  type:
                  - string
                  - 'null'
                  example: null
                Height:
                  type:
                  - string
                  - 'null'
                  example: null
                HeightUnit:
                  type:
                  - string
                  - 'null'
                  example: null
                DressSize:
                  type:
                  - string
                  - 'null'
                  example: null
                OtherInfo:
                  type:
                  - string
                  - 'null'
                  example: null
                SalesSheetImageURL:
                  type:
                  - string
                  - 'null'
                  format: URI
                  example: null
                TotalSubscribers:
                  type: string
                  description: Total subscribers count
                  example: '447364229'
                HaveKids:
                  type:
                  - string
                  - 'null'
                  example: null
                HavePets:
                  type:
                  - string
                  - 'null'
                  example: null
                PoliticalAffiliation:
                  type:
                  - string
                  - 'null'
                  example: null
                PhoneType:
                  type:
                  - string
                  - 'null'
                  example: null
                ShirtSize:
                  type:
                  - string
                  - 'null'
                  example: null
                HasDriverLicense:
                  type:
                  - string
                  - 'null'
             

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