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 row keeps its original columns and gains one column per network. A column is left empty when no profile is found.

Column Type Description
facebook string Facebook page URL.
instagram string Instagram profile URL.
linkedin string LinkedIn company or profile URL.
twitter string X (formerly Twitter) profile URL.
tiktok string TikTok profile URL.
youtube string YouTube channel URL.
pinterest string Pinterest profile URL.

The registry lists social_facebook, social_instagram and so on under produces: these are signal names for the columns above.

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