API access and keys

Connect creator discovery, data lookups, and analysis reports to your application with the hiCreator API.

Get an API key

Authentication

Authenticate requests with your API key using the following HTTP header.

Authorization: Bearer <YOUR_KEY>

API access requires a paid workspace. Calls are billed by usage.

POST/api/openapi/v1/creators/by-email

Find creators by email

API pricing1 credits / matched email, no charge if no creators are found

Supported platformsInstagram / YouTube / TikTok / Twitter / X

Quick start (cURL)

curl -X POST 'https://app.hicreator.ai/api/openapi/v1/creators/by-email' \
  -H 'Authorization: Bearer <YOUR_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "[email protected]"
}'

Request parameters

ParameterTypeRequiredDescription
emailstringYesOne email address to look up.
Supported platforms

Response fields

All matching stored creators; unknown fields are null, no match returns [].

ParameterTypeAlways returnedDescription
requestIdstringYesRequest ID for support.
billingRequestIdstringYesBilling record ID.
dataobjectYesQuery result.
data.emailstringYesQueried email.
data.creatorsobject[]YesMatching creators.
data.creators[].idstringYesPlatform creator ID.
data.creators[].platform'instagram' | 'youtube' | 'tiktok' | 'twitter'YesPlatform.
data.creators[].usernamestring | nullYesHandle.
data.creators[].fullNamestring | nullYesDisplay name.
data.creators[].avatarUrlstring (URL) | nullYesAvatar link.
data.creators[].profileUrlstring (URL) | nullYesCreator profile link.
data.creators[].youtubeChannelUrlstring (URL) | nullYesYouTube channel link.
data.creators[].youtubeHandleUrlstring (URL) | nullYesYouTube handle link.
data.creators[].biographystring | nullYesBiography.
data.creators[].emailstringYesPublic contact email.
data.creators[].externalLinksstring[] | nullYesPublic links.
data.creators[].followerCountinteger | nullYesFollowers or subscribers.
data.creators[].followingCountinteger | nullYesAccounts followed.
data.creators[].regionstring | nullYesRegion.
data.creators[].languagestring | nullYesPrimary content language.
data.creators[].youtubeHasOfficialEmailboolean | nullYesOfficial email button available.
data.creators[].averagePlayCountnumber | nullYesAverage plays.
data.creators[].medianPlayCountnumber | nullYesMedian plays.
data.creators[].averageViewCountnumber | nullYesAverage post views.
data.creators[].medianViewCountnumber | nullYesMedian post views.
data.creators[].averageEngagementRatenumber | nullYesAverage engagement rate as a decimal.
data.creators[].medianEngagementRatenumber | nullYesMedian engagement rate as a decimal.
data.creators[].genderstring | nullYesGender.
data.creators[].ageRangestring | nullYesAge range.
data.creators[].ethnicitystring | nullYesEthnicity.
data.creators[].faceVisibilitystring | nullYesFace visibility.
data.creators[].accountTypestring | nullYesAccount type.
data.creators[].accountPositioningstring[] | nullYesProfile positioning tags.
data.creators[].aiDescriptionstring | nullYesAI creator summary.

Example response (JSON)

{
  "requestId": "<request-id>",
  "billingRequestId": "<billing-request-id>",
  "data": {
    "email": "[email protected]",
    "creators": [
      {
        "id": "123456",
        "platform": "instagram",
        "username": "example_creator",
        "fullName": "Example Creator",
        "avatarUrl": "https://assets.example.com/avatars/creator.jpg",
        "profileUrl": "https://www.instagram.com/example_creator/",
        "youtubeChannelUrl": null,
        "youtubeHandleUrl": null,
        "biography": "Creator biography",
        "email": "[email protected]",
        "externalLinks": [
          "https://example.com/"
        ],
        "followerCount": 50000,
        "followingCount": 120,
        "region": "US",
        "language": "en",
        "youtubeHasOfficialEmail": null,
        "averagePlayCount": 12000,
        "medianPlayCount": 9800,
        "averageViewCount": null,
        "medianViewCount": null,
        "averageEngagementRate": 0.045,
        "medianEngagementRate": 0.041,
        "gender": null,
        "ageRange": null,
        "ethnicity": null,
        "faceVisibility": "clear_face",
        "accountType": null,
        "accountPositioning": [
          "lifestyle creator"
        ],
        "aiDescription": "Lifestyle creator"
      }
    ]
  }
}

Errors and retries

See error.message; keep requestId for support. Do not retry uncertain requests.

View error codes

Request: 400 invalid parameters (10001) or quantity below the minimum (70004); 401 invalid key (20001); 403 API access is only available to paid Workspaces (60006); 413 payload too large (10005); 415 unsupported format (10006); 429 too many requests (10007).

Execution: 404 Twitter creator unavailable (60008); 422 invalid search intent (60001) or target account (60002); 422 email lookup incomplete (60009): search limits reached, fully refunded; this does not mean no email exists and must not be automatically retried; 502 email lookup failed (60003) or execution failed (60004); 504 request timed out (60005). Gateway error pages are returned as JSON with code API_UPSTREAM_ERROR; do not automatically retry paid requests.

Credits: 402 insufficient balance (70001) or daily limit exceeded (70006); 409 feature unavailable (70002) or credit record conflict (70003). API errors include error.code, error.message, and error.requestId. Business errors include error.billingRequestId after charging starts; gateway fallbacks may lack it and cannot confirm refund status.

API access and keys | hiCreator