FR
Copied
Modules

Socials

Enrichment module that attaches public social profile URLs to each point of interest carrying a website.

Purpose

Enrichment module: attaches public social profile URLs (operated by the entity itself) to each POI carrying a website. Parasitic links — share buttons, third-party directories, review aggregators — are discarded. Does not discover entities, verify ownership, or access authenticated content.

Inputs

JSON body with two fields.

Field Type Required Description
items array of objects yes Between 1 and 10 000 points of interest. Each item must carry a site_web field. Items without a website are filtered out before the job is queued.
source_job_id string no Identifier of an upstream job whose output feeds this one. Used to chain modules inside a pipeline.

A minimal item shape is:

{
  "name": "Studio Atlas",
  "site_web": "https://studio-atlas.example"
}

Any additional keys on input items are preserved untouched alongside the social columns.

Outputs

Each input item is returned with the same identifying fields plus one column per network. A column is left empty when no profile is found.

Column Type Description
social_facebook string Canonical Facebook page URL.
social_instagram string Canonical Instagram profile URL.
social_linkedin string Canonical LinkedIn company or profile URL.
social_twitter string Canonical X (formerly Twitter) profile URL.
social_tiktok string Canonical TikTok profile URL.
social_youtube string Canonical YouTube channel URL.

Lifecycle

Standard job lifecycle: see Jobs & lifecycle.

Pipeline

Property Value
Category enrich
Needs site_web
Produces social_facebook, social_instagram, social_linkedin, social_twitter, social_tiktok, social_youtube
Pipelinable yes
Supports continuous monitoring no

Typical chain: scrap → socials → outreach. source_job_id links the run to its parent.

Endpoints

Create a socials job

POST /api/jobs/socials

Request body matches the Inputs table. Response: a Job resource with identifier, queued status, and estimated EF cost.

{
  "items": [
    { "name": "Studio Atlas", "site_web": "https://studio-atlas.example" },
    { "name": "Atelier Nord",  "site_web": "https://atelier-nord.example" }
  ],
  "source_job_id": "b1f2c3d4-..."
}

A successful response returns:

{
  "id": "f9e8d7c6-...",
  "job_type": "socials",
  "status": "pending",
  "items_count": 2,
  "ef_cost": 0.0011
}

Read state, stream progress, download results

Standard job endpoints apply unchanged:

Method Path Purpose
GET /api/jobs/{id} Snapshot of the job state.
GET /api/jobs/{id}/events Server-sent events stream for progress updates.
GET /api/jobs/{id}/results Enriched list, JSON or CSV.

Limits

Global quotas: see /docs/concepts/limits. Module-specific caps:

Limit Value
Items per job 1 to 10 000
Required field per item site_web

Items without a site_web are dropped at validation. If no item remains, the job is rejected.

Errors

Standard HTTP error envelope.

Status Code Condition
400 validation_error The payload fails schema validation (missing items, more than 10 000 entries, malformed JSON).
400 no_eligible_items None of the submitted items carries a usable site_web.
400 quota_exceeded The estimated cost exceeds the account ceiling. The response body carries the estimate and the ceiling.
401 unauthenticated The request is missing a valid session.
403 inactive_account The account is not active.
429 rate_limited Too many job creations in a short window.

Per-item failures never fail the job: empty columns for that item, surfaced in the job summary.

What's next