TikTok Shop

Check pending sample requests against criteria (read only: nothing is approved)

POST/api/public/v1/tik_tok_shop/samples/match
ConnectorAnswers empty results in the documented shape until the brand switches on this connection.

Operation id matchTikTokShopSamples

Request

curl

curl -X POST "https://creator.growthdept.ai/api/public/v1/tik_tok_shop/samples/match" \
  -H "Authorization: Bearer gdc_..." \
  -H "Content-Type: application/json" \
  -d '{"applicationIds":["string"],"criteria":{"categories":["string"],"cooldownDays":3,"excludeSampleStates":["sample_requested"],"maxFollowers":3,"maxProductsSampled":{"max":3,"withinDays":3},"minFollowers":3,"minFulfillmentRate":0.15,"minGmvGlobal30d":{"amount":"string","currency":"usd"},"minPastSampleGmv":{"amount":"string","currency":"usd"},"minPostedRate":0.15,"productIds":["string"]},"cursor":"string","include":"matched","includeFrontierUnresolved":true,"limit":3,"timezone":"string","unknownAs":"fail"}'

Parameters

NameInTypeNotes
organization_idqueryinteger

Request body

FieldTypeNotes
applicationIdsarray of string
criteriaobjectrequired
criteria.categoriesarray of string
criteria.cooldownDaysinteger
criteria.excludeSampleStatesarray of string
criteria.maxFollowersinteger
criteria.maxProductsSampledobject
criteria.maxProductsSampled.maxintegerrequired
criteria.maxProductsSampled.withinDaysintegerrequired
criteria.minFollowersinteger
criteria.minFulfillmentRatenumber
criteria.minGmvGlobal30dobject
criteria.minGmvGlobal30d.amountstringrequired
criteria.minGmvGlobal30d.currencystring
criteria.minPastSampleGmvobject
criteria.minPastSampleGmv.amountstringrequired
criteria.minPastSampleGmv.currencystring
criteria.minPostedRatenumber
criteria.productIdsarray of string
cursorstring
includestringOne of matchedall
includeFrontierUnresolvedboolean
limitinteger
timezonestring
unknownAsstringOne of failpass

Example

{
  "applicationIds": [
    "string"
  ],
  "criteria": {
    "categories": [
      "string"
    ],
    "cooldownDays": 3,
    "excludeSampleStates": [
      "sample_requested"
    ],
    "maxFollowers": 3,
    "maxProductsSampled": {
      "max": 3,
      "withinDays": 3
    },
    "minFollowers": 3,
    "minFulfillmentRate": 0.15,
    "minGmvGlobal30d": {
      "amount": "string",
      "currency": "usd"
    },
    "minPastSampleGmv": {
      "amount": "string",
      "currency": "usd"
    },
    "minPostedRate": 0.15,
    "productIds": [
      "string"
    ]
  },
  "cursor": "string",
  "include": "matched",
  "includeFrontierUnresolved": true,
  "limit": 3,
  "timezone": "string",
  "unknownAs": "fail"
}

Responses

200Success

FieldTypeNotes
approvalsTodayobjectrequired
approvalsToday.localobject, nullablerequired
approvalsToday.local.applicationsintegerrequired
approvalsToday.local.daystring (date)required
approvalsToday.local.fromstring (date-time)required
approvalsToday.local.timezonestringrequired
approvalsToday.local.viaGatewayintegerrequired
approvalsToday.utcobjectrequired
approvalsToday.utc.applicationsintegerrequired
approvalsToday.utc.daystring (date)required
approvalsToday.utc.fromstring (date-time)required
approvalsToday.utc.timezonestringrequired
approvalsToday.utc.viaGatewayintegerrequired
countsobjectrequired
counts.evaluatedintegerrequired
counts.matchedintegerrequired
counts.scannedintegerrequired
itemsarray of objectrequired
items[].[].applicationIdstringrequired
items[].[].creatorIdstringrequired
items[].[].creatorPendingApplicationIdsarray of stringrequired
items[].[].creatorUsernamestring, nullablerequired
items[].[].criteriaobjectrequired
items[].[].criteria.categoriesobject
items[].[].criteria.categories.resultstringrequiredOne of passfailunknown
items[].[].criteria.categories.valuerequired
items[].[].criteria.cooldownDaysobject
items[].[].criteria.cooldownDays.resultstringrequiredOne of passfailunknown
items[].[].criteria.cooldownDays.valuerequired
items[].[].criteria.excludeSampleStatesobject
items[].[].criteria.excludeSampleStates.resultstringrequiredOne of passfailunknown
items[].[].criteria.excludeSampleStates.valuerequired
items[].[].criteria.maxFollowersobject
items[].[].criteria.maxFollowers.resultstringrequiredOne of passfailunknown
items[].[].criteria.maxFollowers.valuenumber, nullablerequired
items[].[].criteria.maxProductsSampledobject
items[].[].criteria.maxProductsSampled.resultstringrequiredOne of passfailunknown
items[].[].criteria.maxProductsSampled.valuerequired
items[].[].criteria.minFollowersobject
items[].[].criteria.minFollowers.resultstringrequiredOne of passfailunknown
items[].[].criteria.minFollowers.valuenumber, nullablerequired
items[].[].criteria.minFulfillmentRateobject
items[].[].criteria.minFulfillmentRate.resultstringrequiredOne of passfailunknown
items[].[].criteria.minFulfillmentRate.valuenumber, nullablerequired
items[].[].criteria.minGmvGlobal30dobject
items[].[].criteria.minGmvGlobal30d.resultstringrequiredOne of passfailunknown
items[].[].criteria.minGmvGlobal30d.valuerequired
items[].[].criteria.minPastSampleGmvobject
items[].[].criteria.minPastSampleGmv.resultstringrequiredOne of passfailunknown
items[].[].criteria.minPastSampleGmv.valuerequired
items[].[].criteria.minPostedRateobject
items[].[].criteria.minPostedRate.resultstringrequiredOne of passfailunknown
items[].[].criteria.minPostedRate.valuerequired
items[].[].criteria.productIdsobject
items[].[].criteria.productIds.resultstringrequiredOne of passfailunknown
items[].[].criteria.productIds.valuerequired
items[].[].firstSeenAtstring (date-time)required
items[].[].frontierUnresolvedbooleanrequired
items[].[].lastSeenAtstring (date-time)required
items[].[].matchedbooleanrequired
items[].[].productsarray of objectrequired
items[].[].products[].[].productIdstring, nullable
items[].[].products[].[].productTitlestring, nullable
nextCursorstring
notestringrequired

Example

{
  "approvalsToday": {
    "local": {
      "applications": 3,
      "day": "2026-11-01",
      "from": "2026-11-01T15:04:05Z",
      "timezone": "string",
      "viaGateway": 3
    },
    "utc": {
      "applications": 3,
      "day": "2026-11-01",
      "from": "2026-11-01T15:04:05Z",
      "timezone": "string",
      "viaGateway": 3
    }
  },
  "counts": {
    "evaluated": 3,
    "matched": 3,
    "scanned": 3
  },
  "items": [
    {
      "applicationId": "string",
      "creatorId": "string",
      "creatorPendingApplicationIds": [
        "string"
      ],
      "creatorUsername": "Example name",
      "criteria": {
        "categories": {
          "result": "pass",
          "value": "string"
        },
        "cooldownDays": {
          "result": "pass",
          "value": "string"
        },
        "excludeSampleStates": {
          "result": "pass",
          "value": "string"
        },
        "maxFollowers": {
          "result": "pass",
          "value": 125.5
        },
        "maxProductsSampled": {
          "result": "pass",
          "value": "string"
        },
        "minFollowers": {
          "result": "pass",
          "value": 125.5
        },
        "minFulfillmentRate": {
          "result": "pass",
          "value": 125.5
        },
        "minGmvGlobal30d": {
          "result": "pass",
          "value": "string"
        },
        "minPastSampleGmv": {
          "result": "pass",
          "value": "string"
        },
        "minPostedRate": {
          "result": "pass",
          "value": "string"
        },
        "productIds": {
          "result": "pass",
          "value": "string"
        }
      },
      "firstSeenAt": "2026-11-01T15:04:05Z",
      "frontierUnresolved": true,
      "lastSeenAt": "2026-11-01T15:04:05Z",
      "matched": true,
      "products": [
        {
          "productId": "string",
          "productTitle": "string"
        }
      ]
    }
  ],
  "nextCursor": "string",
  "note": "string"
}

Errors: 400401403404422429502with an error and usually a message. See errors.

Example values are made up from each field's type and name.