> ## Documentation Index > Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Bulk creator lookup > Looks up to 200 creators at once by `openId`, `oecId` or `username`, using the ids Growi already holds. Send `refs` in the JSON body. Each ref needs at least one id, tried in that order. A leading @ and case are ignored on usernames, and old handles still match. Each result has `found`, `matchedBy` (`openId`, `oecId`, `username` or `previousUsername`), `ambiguous` (more than one stored creator claims the handle or oec id; the pick is still consistent) and `creator`: ids, current and previous usernames, nickname, avatar and stored `facts` (followers, PPS, categories, platform 30-day GMV, fulfillment rate). Results come back in your order. An unknown creator is `found: false`, not an error. Lookup by sec_uid isn't supported. This call doesn't contact TikTok. ## OpenAPI ````yaml api-reference/tik-tok-shop-openapi.json POST /tik_tok_shop/creators/lookup openapi: 3.0.3 info: title: 'Growi API: TikTok Shop' version: 1.0.0 description: >- Generated by scripts/gen_tik_tok_shop.rb from Growi's TikTok Shop route table. servers: - url: https://api.growi.io/api/public/v1 security: - bearerAuth: [] paths: /tik_tok_shop/creators/lookup: post: summary: Bulk creator lookup description: >- Looks up to 200 creators at once by `openId`, `oecId` or `username`, using the ids Growi already holds. Send `refs` in the JSON body. Each ref needs at least one id, tried in that order. A leading @ and case are ignored on usernames, and old handles still match. Each result has `found`, `matchedBy` (`openId`, `oecId`, `username` or `previousUsername`), `ambiguous` (more than one stored creator claims the handle or oec id; the pick is still consistent) and `creator`: ids, current and previous usernames, nickname, avatar and stored `facts` (followers, PPS, categories, platform 30-day GMV, fulfillment rate). Results come back in your order. An unknown creator is `found: false`, not an error. Lookup by sec_uid isn't supported. This call doesn't contact TikTok. parameters: - name: organization_id in: query required: false schema: type: integer description: >- Use the TikTok Shop of this child brand (organization id) of your API key's organization requestBody: required: true content: application/json: schema: type: object required: - refs additionalProperties: false properties: refs: type: array minItems: 1 maxItems: 200 items: type: object additionalProperties: false description: >- At least one id. With several, openId is tried first, then oecId, then username; a ref that names an openId only ever answers with that creator (its oecId or handle landing on someone else is found: false). secUid is not supported: it has no index, so a lookup by it would scan the whole identity table. properties: openId: type: string maxLength: 256 description: TikTok Shop creator open id. oecId: type: string maxLength: 256 description: TikTok creator id (oecuid). username: type: string maxLength: 256 description: Handle. A leading @ and case are ignored. description: >- 1 to 200 creators to look up. Each ref carries at least one of openId, oecId or username; with several, openId is tried first, then oecId, then username. secUid is not accepted. example: refs: - username: '@aly.finds.fun' - oecId: '7494000000000000000' - openId: uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg responses: '200': description: One result per ref, in order. content: application/json: schema: type: object required: - results - counts - note properties: results: type: array items: type: object required: - ref - found - matchedBy - source - ambiguous - creator properties: ref: type: object description: The ref as sent (ids trimmed). found: type: boolean matchedBy: type: string nullable: true enum: - openId - oecId - username - previousUsername - null description: >- Which id matched. previousUsername means the handle now belongs to no stored creator but was this creator's before a rename. source: type: string nullable: true enum: - identity_spine - shop_cache - null description: >- identity_spine: the global identity table. shop_cache: this shop's resolver cache (a creator minted by handle whose oec id the global table never got). ambiguous: type: boolean description: >- More than one stored creator claims this handle or oec id. The pick is still deterministic. creator: type: object nullable: true properties: openId: type: string oecId: type: string nullable: true username: type: string nullable: true previousUsernames: type: array items: type: string secUid: type: string nullable: true description: Public TikTok id, when stored. nickname: type: string nullable: true avatarUrl: type: string nullable: true description: >- Durable R2 mirror URL keyed on secUid. null without a secUid. facts: type: object nullable: true description: >- The same creatorFacts object the relationship.state_changed event carries, from the creator's identity row. Platform-wide and point in time, not this shop's numbers. null when nothing is stored. properties: followerCount: type: number nullable: true pps: type: string description: >- Promotion Performance Score as TikTok sends it. nullable: true fulfillmentRate: type: number description: 90-day sample fulfillment rate, percent. nullable: true medianVideoViews: type: number nullable: true gmv30dAmount: type: string description: Platform-wide 30-day GMV, decimal string. nullable: true gmv30dCurrency: type: string nullable: true contentCount: type: number nullable: true unitsSold: type: number nullable: true categories: type: array nullable: true items: type: string description: >- TikTok category ids. [] means enriched with none, null means never enriched. enrichedAt: type: string nullable: true format: date-time firstSeenAt: type: string nullable: true format: date-time description: null for a shop-cache hit with no identity row. lastSeenAt: type: string nullable: true format: date-time counts: type: object properties: requested: type: integer found: type: integer note: type: string example: results: - ref: username: aly.finds.fun found: true matchedBy: username source: identity_spine ambiguous: false creator: openId: uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg oecId: '7494047584731679211' username: aly.finds.fun previousUsernames: - alyfinds secUid: MS4wLjABAAAABKjQkOz_IIzXXzEAl_9LGsWhvK nickname: ALY avatarUrl: >- https://pub-1ba90224cf014dafb293c586fb03afc0.r2.dev/tiktok_shop/MS4wLjABAAAABKjQkOz_IIzXXzEAl_9LGsWhvK/avatar.jpg facts: followerCount: 5700 pps: '4.2' fulfillmentRate: 96.64 medianVideoViews: 1200 gmv30dAmount: '3500.50' gmv30dCurrency: USD contentCount: 42 unitsSold: 47 categories: - '601739' enrichedAt: '2026-09-20T04:00:00.000Z' firstSeenAt: '2026-06-26T10:00:00.000Z' lastSeenAt: '2026-09-28T02:00:00.000Z' - ref: oecId: '7494000000000000000' found: false matchedBy: null source: null ambiguous: false creator: null counts: requested: 2 found: 1 note: Stored data only, no TikTok call. ... '400': description: >- invalid_request: no refs, more than 200, a ref with no id, an unknown key (secUid included), a sec_uid sent as openId, a blank handle, or a NUL in an id; also a body that is not a valid JSON object content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '403': description: Read-only (viewer) API keys can't call POST endpoints content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '404': description: >- `organization_id` isn't an active child brand of your organization, or the record you asked for doesn't exist content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '422': description: >- No TikTok Shop is connected for this organization. A parent organization whose shops sit on its child brands has to pass `organization_id` content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '429': description: >- Rate limited: one call every 2 seconds and an hourly cap per API key. See `Retry-After` and the `X-RateLimit-*` headers content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' '502': description: >- TikTok refused or failed. `error` is a fixed message and `code` names the failure when there is one content: application/json: schema: $ref: '#/components/schemas/TikTokShopError' components: schemas: TikTokShopError: type: object required: - error properties: error: type: string description: What went wrong code: type: string description: Machine-readable reason, when there is one securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.