Recipe: search to a live Segment

Five calls, start to finish. Every request body below is validated against the same schema the server parses with. Export SPORE_API_KEY first; see Getting started.

1. Search the Commons

Ask the registry the question before you pay to keep the answer. This one is Estonian companies with 2024 revenue over €500M.

{
	"filter": {
		"type": "group",
		"logic": "AND",
		"children": [
			{
				"type": "rule",
				"fieldId": "countryCode",
				"operator": "in",
				"value": ["EE"]
			},
			{
				"type": "rule",
				"fieldId": "revenueEur",
				"operator": "greaterThan",
				"value": 500000000,
				"params": { "years": [2024] }
			}
		]
	},
	"sortBy": "revenue",
	"sortOrder": "desc",
	"maxCredits": 5
}

curl -X POST https://www.spore.ee/api/v1/search \
  -H "Authorization: Bearer $SPORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eu-500m-search-1" \
  -d @search.json

Read count before opening the whole population. Keep both searchResultId and filterHash: the result id identifies this evaluated request and is what the population door takes, while the filter hash identifies its population. The search costs max(5, newly unlocked sample); an identical request — the same filter, sort, and sample size — replays free for 24 hours. Its sample is already Companies of yours, unlocked.

2. Unlock the whole result

The search result's population door mints every matched Legal entity as a Company of your organization and unlocks it. maxCredits is a hard ceiling: the request is refused whole, before anything is minted, if the quote exceeds it, your Company allowance, or your balance.

{
	"searchId": "7f9c2a14-3b6e-4d51-9a2f-1c8e5b0d47a3",
	"maxCredits": 500,
	"dryRun": false
}

curl -X POST https://www.spore.ee/api/v1/search/7f9c2a14-3b6e-4d51-9a2f-1c8e5b0d47a3/unlock \
  -H "Authorization: Bearer $SPORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eu-500m-unlock-1" \
  -d @unlock.json

The response carries matched, mint, unlock, quote, and charged. Only Legal entities you had not unlocked before are charged, at 1 credit each; rights you already hold are free forever. conflicts and incomplete matches are left alone and never charged.

3. Create the live Segment

A Segment stores a name and a filter over your Companies. The Commons search uses its registry vocabulary; the live Segment names each field's origin. Here core.country reads the Company's Core and registry.revenueEur reads unlocked Legal entity data.

{
	"name": "Estonian companies over 500M revenue",
	"filter": {
		"type": "group",
		"logic": "AND",
		"children": [
			{
				"type": "rule",
				"fieldId": "core.country",
				"operator": "equals",
				"value": "EE"
			},
			{
				"type": "rule",
				"fieldId": "registry.revenueEur",
				"operator": "greaterThan",
				"value": 500000000,
				"params": { "years": [2024] }
			}
		]
	}
}

curl -X POST https://www.spore.ee/api/v1/segments \
  -H "Authorization: Bearer $SPORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: eu-500m-segment-1" \
  -d @segment.json

Creating it is free and does no registry work. Keep the returned Segment id. Membership is live: it is evaluated from the stored filter whenever you read its Companies.

4. Read your Companies

The population door created Companies your organization owns. Page them newest first, or read one opaque id from the page:

curl "https://www.spore.ee/api/v1/companies?country=EE&limit=50" \
  -H "Authorization: Bearer $SPORE_API_KEY"

curl https://www.spore.ee/api/v1/companies/$COMPANY_ID \
  -H "Authorization: Bearer $SPORE_API_KEY"

Both reads are free. The list returns each Company's Core under an opaque cursor. The single-Company read adds its Legal entity section; because step 2 unlocked this population, that section contains the live registry record rather than only an unlock price.

5. Read the Segment and its live members

Read the Segment's name, filter, and strong ETag, then page the Companies matching it now:

curl https://www.spore.ee/api/v1/segments/$SEGMENT_ID \
  -H "Authorization: Bearer $SPORE_API_KEY"

curl "https://www.spore.ee/api/v1/segments/$SEGMENT_ID/companies?limit=50" \
  -H "Authorization: Bearer $SPORE_API_KEY"

The member response is { items, nextCursor, total }; total is the exact count of the whole matching set. Both calls are free. Registry predicates are evaluated only over Legal entities the organization has unlocked, so a verified-but-locked Company cannot enter the Segment. Edit the Segment's filter later and the next member read reflects the change immediately.

Next