TikTok-leads op IG controleren vóór overdracht aan het CRM

Een marketeer kan op TikTok een video vinden van een maker die een relevant product bespreekt, maar de stap van zo’n signaal naar een controleerbaar contact is lastiger: de naam van de maker op TikTok kan verschillen van die op IG, en het profiel kan privé zijn of helemaal geen bevestigde koppeling met de persoon hebben. Een bruikbaar resultaat is geen automatische lijst met ‘klare leads’, maar een controletabel: de oorspronkelijke video, de TikTok-auteur, de vermoedelijke IG-gebruikersnaam, de API-respons en een status voor verdere beoordeling.

Hieronder staat een minimale Python-workflow voor deze taak. Die zoekt naar openbare video’s op basis van een trefwoord, haalt beschikbare auteursgegevens op en controleert IG-profielen alleen als je al een onderbouwde gebruikersnaam hebt om te controleren. De API kan profielgegevens opvragen aan de hand van een gebruikersnaam; ze stelt niet automatisch vast dat twee accounts van dezelfde persoon zijn.

Welk resultaat kun je automatiseren?

Stel je een team voor dat apparatuur voor thuisbarista’s verkoopt en makers van openbare video’s over het bereiden van dranken wil vinden. Handmatig zoeken is nuttig om content voor het eerst te verkennen, maar bij herhaald gebruik is het lastig bij te houden welke video tot een contact leidde, waar de profielnaam vandaan kwam en wat precies is gecontroleerd.

De pipeline verdeelt het werk in drie handelingen: video’s zoeken op TikTok, waargenomen gegevens opslaan en het vermoedelijke IG-profiel controleren. Zo kan een analist één CSV-bestand openen en de herkomst van elke kandidaat volgen. Vul IG-velden alleen in nadat de gebruikersnaam is gevonden in een openbare profielbeschrijving, een link van de maker of door iemand aan de hand van ander beschikbaar materiaal is gecontroleerd.

Deze aanpak is nuttig voor een bureau, een onderzoeksteam of een interne marketeer die een kleine, reproduceerbare lijst voor handmatige kwalificatie nodig heeft. De context van de vondst blijft behouden en overeenkomende namen worden niet als bewijs van identiteit gepresenteerd.

Welke velden kun je ophalen?

De gedocumenteerde TikTok-route /searchVideo vereist de parameter keyword; ook count, date_posted, sort_by, region en cursor zijn beschikbaar. In waargenomen antwoorden komen een video-ID, beschrijving, publicatiedatum, link, auteursgegevens en openbare interactiestatistieken voor. De daadwerkelijke velden kunnen verschillen; daarom gebruikt de code hieronder veilige uitlezing met lege waarden.

Voor IG gebruikt deze workflow de gedocumenteerde GET-route /v1/user/by/username met de parameter username. Het antwoord kan de gebruikersnaam, weergavenaam, privacy- en verificatiestatus, aantallen berichten, volgers en gevolgde accounts, en de biografie bevatten. Dit zijn gegevens voor inzage en verdere beoordeling door een specialist, geen beoordeling van de maker.

De officiële documentatie van de TikTok API beschrijft de zoekparameters, terwijl de documentatie van de IG API de methoden en parameters voor IG beschrijft. De ingebouwde API-definities van jsonscraper leggen ook routes, parameternamen en waargenomen antwoordstructuren vast; de vermelde controles zijn uitgevoerd op 25 oktober 2026.

Stel sleutels en de kandidatenlijst in

Sla API-sleutels op in omgevingsvariabelen: JSONSCRAPER_TIKTOK_LICENSE_KEY en JSONSCRAPER_INSTAGRAM_LICENSE_KEY. Zet ze niet in de broncode, CSV-bestanden of taaklogboeken. Installeer de requests-bibliotheek met python -m pip install requests. Het volgende voorbeeld is bedoeld voor Python 3.8 en hoger.

import csv
import os
import sys
from urllib.parse import urlencode

import requests

TIKTOK_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
INSTAGRAM_KEY = os.environ.get("JSONSCRAPER_INSTAGRAM_LICENSE_KEY")

if not TIKTOK_KEY or not INSTAGRAM_KEY:
    sys.exit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY and JSONSCRAPER_INSTAGRAM_LICENSE_KEY")


def get_json(base_url, path, params):
    response = requests.get(
        f"{base_url}{path}",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


def extract_videos(payload):
    """Handle both observed TikTok search result locations."""
    if payload.get("status") != "ok":
        raise RuntimeError(f"TikTok API status: {payload.get('status')}")

    tiktok = payload.get("tiktok") or {}
    videos = list(tiktok.get("aweme_list") or [])
    for item in tiktok.get("search_item_list") or []:
        video = item.get("aweme_info")
        if video:
            videos.append(video)

    unique = {}
    for video in videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


keyword = "домашний кофе"
tiktok_payload = get_json(
    "https://tiktok.evelode.com",
    "/searchVideo",
    {
        "license_key": TIKTOK_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-month",
        "sort_by": "relevance",
    },
)

rows = []
for video in extract_videos(tiktok_payload):
    author = video.get("author") or {}
    stats = video.get("statistics") or {}
    rows.append({
        "tiktok_video_id": video.get("aweme_id", ""),
        "tiktok_url": video.get("share_url", ""),
        "video_description": video.get("desc", ""),
        "created_at": video.get("create_time", ""),
        "tiktok_username": author.get("unique_id", ""),
        "tiktok_author_name": author.get("nickname", ""),
        "tiktok_followers": author.get("follower_count", ""),
        "views": stats.get("play_count", ""),
        "likes": stats.get("digg_count", ""),
        "instagram_username": "",
        "instagram_status": "not checked",
        "instagram_followers": "",
        "instagram_is_private": "",
        "manual_match_review": "required",
    })

# Заполняйте этот словарь только username, найденными отдельно
# и внесёнными после ручной проверки источника.
verified_instagram_usernames = {
    # "tiktok_video_id": "instagram_username"
}

for row in rows:
    username = verified_instagram_usernames.get(row["tiktok_video_id"])
    if not username:
        continue

    ig_payload = get_json(
        "https://ig.jsonscraper.com",
        "/v1/user/by/username",
        {
            "license_key": INSTAGRAM_KEY,
            "username": username,
        },
    )
    if ig_payload.get("status") != "ok":
        row["instagram_status"] = "api status: " + str(ig_payload.get("status"))
        continue

    profile = ig_payload.get("ig") or {}
    row["instagram_username"] = profile.get("username", username)
    row["instagram_status"] = "profile returned"
    row["instagram_followers"] = profile.get("follower_count", "")
    row["instagram_is_private"] = profile.get("is_private", "")
    row["manual_match_review"] = "check relationship manually"

if rows:
    with open("social_lead_checks.csv", "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=rows[0].keys())
        writer.writeheader()
        writer.writerows(rows)
else:
    print("No video rows returned for this query.")

Waarom de handler rekening houdt met twee antwoordstructuren

Bij TikTok-zoekopdrachten kunnen video’s op twee plekken staan: tiktok.aweme_list en tiktok.search_item_list[].aweme_info. In een waargenomen zoekantwoord kon de eerste lijst leeg zijn, terwijl de resultaten wel in de tweede stonden. Daarom combineert het voorbeeld beide bronnen en verwijdert het duplicaten op basis van aweme_id. Eerst controleert de code de buitenste status, daarna leest die het object tiktok.

De code slaat alleen velden op die daadwerkelijk in het antwoord aanwezig zijn. Een lege waarde betekent dat het veld ontbrak in het ontvangen object; je mag die niet als een nulwaarde interpreteren. Het is nuttig om videolinks en beschrijvingen samen met de statistieken te bewaren: anders verliest de tabel bij latere inzage de oorspronkelijke context.

Voeg alleen paginering toe als dat nodig is

Het voorbeeld vraagt één pagina op en verwerkt alleen de geretourneerde items. Als je de zoekopdracht wilt voortzetten, voorziet de documentatie in cursor voor videozoekopdrachten; de waarde komt uit het vorige antwoord. Bewaar de cursor als een ondoorzichtige waarde en geef die door zonder zelf berekeningen uit te voeren. Stop de lus wanneer het antwoord aangeeft dat er geen vervolg is, of wanneer de ingestelde limiet van het team is bereikt. Paginering breidt de set geretourneerde resultaten uit, maar geeft geen reden om die een volledig overzicht van alle publicaties over het onderwerp te noemen.

Controleer het daadwerkelijke antwoord met je eigen sleutel voordat je automatische export toevoegt en kies een bescheiden aantal pagina’s. Bewaar de oorspronkelijke JSON naast de genormaliseerde rij of apart per uitvoerdatum. Zo kun je nagaan of een antwoordveld is veranderd en de verzameling opnieuw verwerken als het schema wijzigt.

De CSV gebruiken voor kwalificatie

In de tabel kun je filteren op de aanwezigheid van een videolink, beschrijving, auteur en ingevuld IG-profiel. Voor een eerste controle zijn eenvoudige statussen bruikbaar: ‘video gevonden’, ‘IG-gebruikersnaam gevonden’, ‘profiel geretourneerd’, ‘accountkoppeling door een persoon gecontroleerd’ en ‘uitgesloten’. De statussen beschrijven het controleproces, niet de kwaliteit of intentie van de maker.

Als de taak een herhaalbaar rapport vereist, voer het script dan volgens een schema uit en voeg de ophaaldatum toe in een afzonderlijke kolom. Door momentopnamen te vergelijken zie je vervolgens wat er tussen uitvoeringen is veranderd in de beschikbare velden, bijvoorbeeld het aantal profielvolgers. Bewaar TikTok- en IG-statistieken gescheiden, met vermelding van platform en waarnemingstijd: het zijn verschillende contexten en verschillende API-antwoorden.

Vervang voor een grotere stroom de CSV door een database met een primaire sleutel op basis van platform en video-ID. Bewaar de oorspronkelijke tekstuele zoekopdracht, het verzameltijdstip en het onbewerkte antwoord. Verstuur pas een melding naar Slack of een rij naar het CRM nadat de profielkoppeling handmatig is bevestigd, niet direct na een overeenkomst in naam.

Interpretatiegrenzen en veilig gebruik

Zoeken op een trefwoord levert gevonden API-resultaten op, geen volledige lijst met publicaties. Het aantal weergaven, likes en volgers is een momentopname van het antwoord op het tijdstip van de aanvraag. Die gegevens zijn geschikt om een werklijst te sorteren en verder te controleren, maar bevestigen op zichzelf geen commerciële intentie, doelgroep of toestemming voor contact.

Bevestig profielkoppelingen aan de hand van duidelijke openbare aanwijzingen en leg vast wie de controle heeft uitgevoerd en wanneer. Als een IG-gebruikersnaam uit een externe tabel komt zonder verifieerbare bron, laat de status dan op ‘controle vereist’ staan. Een privéprofiel of ontbrekende gegevens moet als afzonderlijk controleresultaat worden weergegeven, zonder de lacune met een aanname op te vullen.

Gebruik sleutels in de geheime-opslag van de werkomgeving, beperk de toegang tot exports en stel een bewaartermijn vast die past bij het onderzoeksdoel. Geef alleen velden door aan het CRM die nodig zijn voor het verdere handmatige werk, en houd je aan de toepasselijke platformregels en vereisten voor gegevensverwerking.

Het eindresultaat

Na uitvoering verschijnt er een CSV met gevonden video’s, auteurs en beschikbare statistieken, plus afzonderlijke velden voor de controle van IG. Je kunt het script handmatig uitvoeren, volgens een schema in CI of via een HTTP-requestnode in een automatiseringsplatform. Het belangrijkste praktische principe is dat je het verzamelen en structureren van gegevens automatiseert, terwijl een mens de controleerbare stap uitvoert om de accounts aan elkaar te koppelen.

Begin voor het controleren van routes en beschikbare parameters met de TikTok Scraper API en de IG Scraper API. De productpagina’s bevatten aanvraagvoorbeelden en links naar de documentatie; begin met een kleine aanvraag voordat je het verzamelen in een permanent proces integreert.