Bulk creator lookup
curl --request POST \
--url https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"refs": [
{
"username": "@aly.finds.fun"
},
{
"oecId": "7494000000000000000"
},
{
"openId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg"
}
]
}
'import requests
url = "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup"
payload = { "refs": [{ "username": "@aly.finds.fun" }, { "oecId": "7494000000000000000" }, { "openId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" }] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
refs: [
{username: '@aly.finds.fun'},
{oecId: '7494000000000000000'},
{openId: 'uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg'}
]
})
};
fetch('https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'refs' => [
[
'username' => '@aly.finds.fun'
],
[
'oecId' => '7494000000000000000'
],
[
'openId' => 'uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup"
payload := strings.NewReader("{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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. ..."
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}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.
POST
/
tik_tok_shop
/
creators
/
lookup
Bulk creator lookup
curl --request POST \
--url https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"refs": [
{
"username": "@aly.finds.fun"
},
{
"oecId": "7494000000000000000"
},
{
"openId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg"
}
]
}
'import requests
url = "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup"
payload = { "refs": [{ "username": "@aly.finds.fun" }, { "oecId": "7494000000000000000" }, { "openId": "uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg" }] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
refs: [
{username: '@aly.finds.fun'},
{oecId: '7494000000000000000'},
{openId: 'uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg'}
]
})
};
fetch('https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'refs' => [
[
'username' => '@aly.finds.fun'
],
[
'oecId' => '7494000000000000000'
],
[
'openId' => 'uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup"
payload := strings.NewReader("{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growi.io/api/public/v1/tik_tok_shop/creators/lookup")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"refs\": [\n {\n \"username\": \"@aly.finds.fun\"\n },\n {\n \"oecId\": \"7494000000000000000\"\n },\n {\n \"openId\": \"uACafQAAAABmUU2qon4R0vUYvUVS3QC6CICP2m5A2-wd77j8R9G0yg\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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. ..."
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Use the TikTok Shop of this child brand (organization id) of your API key's organization
Body
application/json
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.
Required array length:
1 - 200 elementsShow child attributes
Show child attributes