REST API

Build with diaspora
intelligence.

Sporafind's REST API gives you programmatic access to the world's richest Ghanaian diaspora intelligence — profiles, organisations, segmentation signals, and export pipelines. Use it to embed diaspora data into your own tools, workflows, and platforms.

Base URL https://api.sporafind.com/v1 v1.0 — Stable

Introduction

Welcome to the Sporafind API. Every endpoint returns JSON responses and uses standard HTTP status codes. All requests must be made over HTTPS. The API is organised around profiles and organisations — the two core objects in our intelligence model.

We support cursor-based pagination for all list endpoints. Each response includes a next_cursor field that can be passed as a query parameter to fetch the next page.

New to Sporafind? Every API response includes a request_id header that you can reference when contacting support.

Authentication

Authenticate all requests by including a Bearer token in the Authorization header. You can generate API tokens from your Sporafind dashboard under Settings → API Keys.

          
          cURL
        
curl https://api.sporafind.com/v1/profiles/search \
  -H "Authorization: Bearer df_live_abc123def456"

Keep your tokens secure. Never share tokens in client-side code or public repositories. Rotate tokens regularly from your dashboard. Use restricted-scope tokens for development environments.

Rate limits

Rate limits vary by plan. Every response includes rate-limit headers so you can monitor your usage. Exceeding the limit returns a 429 Too Many Requests status.

Plan	Requests / minute	Requests / day	Burst limit
Starter	30	5,000	10
Growth	120	50,000	30
Enterprise	Custom	Custom	Custom

Rate limit headers returned with every response:

Header	Description
`X-RateLimit-Limit`	Max requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Search profiles

Searches the diaspora intelligence index and returns matching profiles. Supports full-text search across names, locations, industries, and organisations, combined with segment and demographic filters.

GET /profiles/search Search diaspora profiles

Query parameters

Parameter	Type	Description
qoptional	string	Full-text search query (names, locations, industries, organisations)
segmentoptional	string	Filter by segment. One of: regular leader entrepreneur investor
countryoptional	string	ISO 3166-1 alpha-2 country code (e.g. GB, US, CA)
industryoptional	string	Industry cluster. One of: fintech healthcare tech real_estate energy education
wealth_tieroptional	string	Wealth signal filter: hnw uhnw mass_affluent
min_confidenceoptional	number	Minimum AI confidence score (0–100). Only returns profiles above this threshold.
cursoroptional	string	Pagination cursor from a previous response's `next_cursor` field.
limitoptional	integer	Number of results per page (1–100). Default: 25

Example request

              
              cURL
            
curl "https://api.sporafind.com/v1/profiles/search?q=fintech+founder+london&segment=entrepreneur&wealth_tier=hnw&limit=10" \
  -H "Authorization: Bearer df_live_abc123def456"

Response

              
              JSON
            
{
  "data": [
    {
      "id": "prof_9x7k2m4n",
      "name": "Kwame Mensah",
      "segment": "entrepreneur",
      "country": "GB",
      "city": "London",
      "industry": "fintech",
      "wealth_tier": "hnw",
      "confidence": 94,
      "title": "Founder & CEO",
      "organisation": "KudiPay",
      "linkedin_url": "https://linkedin.com/in/kwamemensah",
      "signals": ["company_registration", "media_mention", "investor_network"],
      "last_updated": "2026-06-20T14:32:00Z"
    }
  ],
  "total": 342,
  "next_cursor": "eyJwYWdlIjoxfQ==",
  "has_more": true
}

Get profile

Retrieves a single diaspora profile by its unique ID, including all enrichment data, segment classification, and signal metadata.

GET /profiles/{id} Retrieve a single profile

Path parameters

Parameter	Type	Description
idrequired	string	Unique profile identifier (e.g. `prof_9x7k2m4n`)

Query parameters

Parameter	Type	Description
include_signalsoptional	boolean	Include full signal breakdown in response. Default: false

Example request

              
              cURL
            
curl https://api.sporafind.com/v1/profiles/prof_9x7k2m4n \
  -H "Authorization: Bearer df_live_abc123def456"

Response

              
              JSON
            
{
  "id": "prof_9x7k2m4n",
  "name": "Kwame Mensah",
  "segment": "entrepreneur",
  "country": "GB",
  "city": "London",
  "industry": "fintech",
  "wealth_tier": "hnw",
  "confidence": 94,
  "title": "Founder & CEO",
  "organisation": "KudiPay",
  "linkedin_url": "https://linkedin.com/in/kwamemensah",
  "signals": ["company_registration", "media_mention", "investor_network"],
  "signal_breakdown": {
    "company_registration": { "source": "companies_house", "verified": true, "date": "2024-03-15" },
    "media_mention": { "source": "tech_crunch", "verified": true, "date": "2025-09-02" },
    "investor_network": { "source": "crunchbase", "verified": false, "date": "2026-01-10" }
  },
  "engagement_angle": "Fintech founder with Series A exit. Approach via investor networks or Ghana fintech events in London.",
  "last_updated": "2026-06-20T14:32:00Z"
}

Organisations

Returns diaspora organisations matching the search criteria. This endpoint mirrors the same intelligence model used for profiles but scoped to associations, investment syndicates, professional bodies, community organisations, and think tanks.

GET /organisations List and search organisations

Query parameters

Parameter	Type	Description
qoptional	string	Full-text search across organisation name, description, and country
org_typeoptional	string	One of: association syndicate professional_body community think_tank
countryoptional	string	ISO 3166-1 alpha-2 country code
min_membersoptional	integer	Minimum estimated membership count
cursoroptional	string	Pagination cursor
limitoptional	integer	Results per page (1–100). Default: 25

Example request

              
              cURL
            
curl "https://api.sporafind.com/v1/organisations?org_type=syndicate&country=US&limit=20" \
  -H "Authorization: Bearer df_live_abc123def456"

Response

              
              JSON
            
{
  "data": [
    {
      "id": "org_3m8n1k9p",
      "name": "Ghanaian Angel Network USA",
      "org_type": "syndicate",
      "country": "US",
      "city": "New York",
      "members_estimated": 340,
      "leadership": ["Dr. Esi Asare", "Yaw Boateng"],
      "focus_sectors": ["fintech", "real_estate", "agritech"],
      "confidence": 87,
      "last_updated": "2026-06-18T09:15:00Z"
    }
  ],
  "total": 128,
  "next_cursor": "eyJwYWdlIjoyfQ==",
  "has_more": true
}

Saved lists

Retrieve and manage your saved profile and organisation lists. Lists are created from the Sporafind dashboard or via the API and persist across sessions.

GET /lists List all saved lists

Query parameters

Parameter	Type	Description
cursoroptional	string	Pagination cursor
limitoptional	integer	Results per page (1–100). Default: 25

Example request

              
              cURL
            
curl https://api.sporafind.com/v1/lists \
  -H "Authorization: Bearer df_live_abc123def456"

Response

              
              JSON
            
{
  "data": [
    {
      "id": "list_4k7n2m9x",
      "name": "London Fintech Investors",
      "profile_count": 47,
      "org_count": 12,
      "created_at": "2026-05-12T10:30:00Z",
      "last_updated": "2026-06-22T16:45:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

GET /lists/{id} Get list contents

Path parameters

Parameter	Type	Description
idrequired	string	List identifier (e.g. `list_4k7n2m9x`)

Example request

              
              cURL
            
curl https://api.sporafind.com/v1/lists/list_4k7n2m9x \
  -H "Authorization: Bearer df_live_abc123def456"

Export data

Export filtered profile and organisation data as CSV. Exports are generated asynchronously and delivered via a download URL. This endpoint is ideal for CRM imports, offline analysis, and reporting.

POST /exports Create an export job

Request body

Field	Type	Description
typerequired	string	Export type: profiles or organisations
filtersrequired	object	Filter object using the same parameters as the search endpoints (segment, country, industry, etc.)
formatoptional	string	Export format. Default: csv
list_idoptional	string	Export from a saved list instead of ad-hoc filters

Example request

              
              cURL
            
curl https://api.sporafind.com/v1/exports \
  -H "Authorization: Bearer df_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"type":"profiles","filters":{"segment":"investor","country":"GB","min_confidence":80},"format":"csv"}'

Response

              
              JSON
            
{
  "id": "exp_2n5k8m1q",
  "status": "processing",
  "type": "profiles",
  "format": "csv",
  "estimated_rows": 1800,
  "download_url": null,
  "created_at": "2026-06-25T08:12:00Z"
}

Polling for completion

GET /exports/{id} Check export status

Poll this endpoint to check when the export is ready. Once status changes to completed, the download_url will be populated and available for 24 hours.

Profile object

The profile object is the core data model in Sporafind. Every profile represents a diaspora individual with segment classification, location data, and AI-derived intelligence signals.

Field	Type	Description
id	string	Unique profile identifier (prefixed `prof_`)
name	string	Full name of the individual
segment	string	AI-classified segment: regular leader entrepreneur investor
country	string	ISO 3166-1 alpha-2 country code of residence
city	string	City of residence
industry	string	Primary industry cluster
wealth_tier	string	Wealth signal: mass_affluent hnw uhnw
confidence	integer	Overall AI signal confidence (0–100)
title	string	Professional title or role
organisation	string	Current or primary organisation
linkedin_url	string	LinkedIn profile URL (when available)
signals	array	List of signal types detected for this profile
signal_breakdown	object	Detailed signal metadata per source (requires `include_signals=true`)
engagement_angle	string	AI-generated recommended outreach approach
last_updated	string	ISO 8601 timestamp of last update

Organisation object

The organisation object represents diaspora associations, syndicates, professional bodies, community organisations, and think tanks identified by our intelligence engine.

Field	Type	Description
id	string	Unique organisation identifier (prefixed `org_`)
name	string	Organisation name
org_type	string	Classification: association syndicate professional_body community think_tank
country	string	ISO 3166-1 alpha-2 country code
city	string	City of headquarters or primary operations
members_estimated	integer	Estimated membership count
leadership	array	List of identified leaders or officers
focus_sectors	array	Industry sectors the organisation operates in
confidence	integer	AI signal confidence (0–100)
last_updated	string	ISO 8601 timestamp of last update

Error responses

The Sporafind API uses conventional HTTP status codes to indicate success or failure. Error bodies always follow the same structure.

Status	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters or malformed request body
401	Unauthorized	Missing or invalid API token
403	Forbidden	Token lacks permissions for the requested resource
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Something went wrong on our side

Error response body

          
          JSON
        
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API token. Generate a new token from the dashboard.",
    "code": "invalid_token",
    "request_id": "req_8k2m4n7x",
    "docs_url": "https://docs.sporafind.com/api#authentication"
  }
}

SDKs & libraries

Use our official client libraries to integrate Sporafind into your stack. All libraries are open-source and wrap the REST API with typed interfaces.

Python

Native async support, complete type annotations, and pandas integration for data workflows.

View on GitHub

JavaScript / TypeScript

Full TypeScript definitions, Node.js and browser support, with Express middleware helpers.

View on GitHub

Ruby

Rails-compatible gem with ActiveRecord-style query chaining and built-in caching.

View on GitHub

PHP

Laravel package with facades, queued export handling, and webhook signature verification.

View on GitHub

Lightweight client with context support, retry logic, and zero external dependencies.

View on GitHub

Community SDKs

Community-maintained clients for Rust, Elixir, .NET, and Java. Contributions welcome.

Browse all SDKs

Webhooks

Webhooks enable real-time event notifications from Sporafind. Subscribe to events like profile enrichment completion, export readiness, and list updates — and Sporafind will POST the payload to your endpoint.

Verifying webhook signatures. Every webhook request includes a X-Sporafind-Signature header. Verify signatures using your webhook secret to ensure the payload came from Sporafind and hasn't been tampered with.

profile.enriched

Fires when a profile has been fully enriched with new signals or data sources.

profile.enriched

export.completed

Fires when an asynchronous export job has finished and the download URL is ready.

export.completed

list.updated

Fires when a saved list gains or loses members after a refresh.

list.updated

alert.threshold

Fires when a custom alert threshold is met (e.g. new profiles in a saved search).

alert.threshold

Webhook payload format

          
          JSON
        
{
  "event": "export.completed",
  "created": "2026-06-25T10:30:00Z",
  "data": {
    "export_id": "exp_2n5k8m1q",
    "status": "completed",
    "download_url": "https://api.sporafind.com/v1/exports/exp_2n5k8m1q/download",
    "row_count": 1800
  }
}

Configure webhook endpoints from your Sporafind dashboard under Settings → Webhooks. You can set up to 5 webhook endpoints per account on the Growth plan and above.

Build with diaspora intelligence.

Introduction

Authentication

Rate limits

Search profiles

Query parameters

Example request

Response

Get profile

Path parameters

Query parameters

Example request

Response

Organisations

Query parameters

Example request

Response

Saved lists

Query parameters

Example request

Response

Path parameters

Example request

Export data

Request body

Example request

Response

Polling for completion

Profile object

Organisation object

Error responses

Error response body

SDKs & libraries

Webhooks

Webhook payload format

Build with diaspora
intelligence.