Aleph FollowTheMoney Extractor

Point at an Aleph deployment you can access and pull structured FollowTheMoney (FtM) investigative-graph data from its /api/2 API. Aleph is the entity-graph platform that OCCRP and the investigative-journalism network run on top of the FollowTheMoney data standard — this actor turns a reachable Aleph base into clean, structured rows for AML, due-diligence, and OSINT research.

Buyer-first anonymous source: https://source.bird.tools exposes a verified public collections catalogue. API keys are optional only for deployments or public subsets proven anonymous. Access varies by deployment and endpoint; current OCCRP collections/entities are auth-gated and require an API key.

Three modes

Mode	Endpoint	One row =
collections	/api/2/collections	one dataset/collection in the instance (label, category, count, restricted/secret flags, frequency, dates)
entities	/api/2/entities	one FtM entity — Person, Company, Sanction, Address … (id, schema, extracted name/countries/dates + the full multi-valued properties blob, its collection)
metadata	/api/2/metadata	one FtM schema the instance self-describes (Person, Company, …) with its label, plural, description, and property count — the discovery map of what an instance can serve

Input

Field	Type	Notes
alephUrl	string (required)	An Aleph base, e.g. https://source.bird.tools. Bare host or a /api/2 URL both work.
mode	enum	collections | entities | metadata (default collections).
query	string	Entities: q= full-text (e.g. a name). See the note below.
schema	string	Entities: restrict to one FtM schema (Person, Company, Sanction, …). The reliable structured query path.
collectionId	string	Entities: scope to one collection by its numeric collection_id.
maxRecords	integer	Cap on emitted rows (default 5). One row = one billable record.
apiKey	string (secret)	Optional only for deployments/public subsets proven anonymous; required for restricted content or auth-gated deployments, including current OCCRP collections/entities.
extraHeaders	object	Optional extra request headers.

Example inputs

{"alephUrl":"https://source.bird.tools","maxRecords":5,"mode":"collections"}

This bounded BIRN collections input is the proven anonymous buyer default. It returns at most five genuine catalogue rows, keeping the first run cheap and predictable.

Entity mode is not proven as an anonymous buyer default on BIRN or the independent DDoSecrets corroboration deployment. Use entities only against a deployment and filter you have verified, and provide apiKey when required.

{"alephUrl":"https://source.bird.tools","maxRecords":5,"mode":"metadata"}

Notes on reliability

• Pagination is standard offset paging (page/limit/total/pages with an absolute next link) — the actor follows it to maxRecords.
• Full-text search can 500 transiently. Aleph's q= backend can return a transient HTTP 500 under load while structured filter:schema= queries stay healthy. The actor retries 5xx/429 with backoff and treats a 500 as a server-side condition, not an empty result — so it never fabricates or silently reports empty. If a query run struggles, prefer a schema filter.
• Restricted / secret collections are surfaced with their flags so a private collection is never mistaken for empty. Provide apiKey whenever the deployment requires authorization; current OCCRP collections/entities do.
• No fabricated output. An unreachable base, a non-Aleph host, or a genuinely empty result fails fast rather than emitting invented rows.

Output

One flat, fully-nullable JSON row per record. Only _mode and _alephUrl are always set; every domain field is nullable because the three modes and the wildly varying FtM schemas populate different columns. The multi-valued FtM properties are preserved as a JSON string in properties, with common values also extracted to name / countries / dates.

Pricing

Pay-per-event — one record charge per emitted entity / collection / schema.