For App Developers

Needs & Commitments

The Global.Church API supports a three-step engagement lifecycle that connects gaps to action:

Need — an organization declares that work is needed within a particular scope (an engagement accelerator, a people group, a country).
Commitment — an organization commits to act in a specific scope. A commitment may respond to a prior need, or stand alone.
Engagement attestation — an organization attests that engagement has occurred. The attestation may optionally fulfill a commitment.

Every step writes to a Supabase table backing the API and propagates to the knowledge graph in near-real-time. SPARQL queries can traverse gc:concernsNeed (Commitment → Need) and gc:fulfillsCommitment (Attestation → Commitment) to walk the full chain.

Authentication

All write endpoints in this lifecycle (POST /v0/needs, POST /v0/commitments, POST /v0/engagement-claims/submit, the /status endpoints) require the caller to have an active membership for the organization referenced by orgUri. Pass your API key as Authorization: Bearer <key> and supply the user's email in declaredByEmail (or claimedByEmail for engagement attestations) so the membership check can run.

Read endpoints (GET /v0/needs, GET /v0/commitments, GET /v0/engagement-claims) require the API key but no per-organization membership.

Step 1 — Declare a need

Code
 
curl -X POST https://api.global.church/v0/needs \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/example-mission",
    "orgName": "Example Mission",
    "declaredByEmail": "[email protected]",
    "needDescription": "Audio scripture in Kazakh dialect XYZ for oral-preference communities along the eastern border.",
    "accelerators": ["SRA-AUD"],
    "concernsPeopleGroupRop3": ["115648"],
    "concernsCountryCode": ["KZ"]
  }'

Code
 
{ "needId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234", "status": "open" }

Required fields: orgUri, orgName, declaredByEmail, needDescription, and a non-empty accelerators array of gc:EngagementAcceleratorScheme notation codes.

Optional concernsPeopleGroupRop3 (ROP3 codes) and concernsCountryCode (ISO alpha-2) narrow the scope. A need may carry multiple accelerators, multiple people groups, and multiple countries.

Need statuses

Status	Meaning
`open`	Default at creation. The need has not been met.
`partially_met`	One or more commitments have addressed part of the need.
`met`	The need has been fully addressed.
`withdrawn`	The declaring organization has rescinded the need.

Transition with POST /v0/needs/status:

Code
 
curl -X POST https://api.global.church/v0/needs/status \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "needId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234",
    "status": "partially_met",
    "actorEmail": "[email protected]"
  }'

Any status is reachable from any other so users can correct mistakes; there is no enforced state machine.

Step 2 — Make a commitment

A commitment may respond to a known need or stand alone. To respond to a need, include concernsNeedId:

Code
 
curl -X POST https://api.global.church/v0/commitments \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/audio-scripture-org",
    "orgName": "Audio Scripture Org",
    "declaredByEmail": "[email protected]",
    "commitmentDescription": "Produce and distribute the Kazakh-XYZ Audio New Testament by Q4 2027.",
    "acceleratorScope": ["SRA-AUD"],
    "concernsNeedId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234",
    "concernsPeopleGroupRop3": ["115648"],
    "concernsCountryCode": ["KZ"],
    "targetCompletionDate": "2027-12-31"
  }'

Code
 
{ "commitmentId": "6a91f5c4-3e22-4db8-bc34-7e9af0124567", "status": "declared" }

Required: orgUri, orgName, declaredByEmail, commitmentDescription, acceleratorScope. Optional: concernsNeedId, concernsPeopleGroupRop3, concernsCountryCode, targetCompletionDate (ISO YYYY-MM-DD).

If concernsNeedId is supplied, the API verifies the need exists. The need's owning organization need not match the committing organization — any organization may commit against any open need.

Commitment statuses

Status	Meaning
`declared`	Default at creation. Commitment is recorded but no funding or work has begun.
`funded`	Resources have been allocated.
`in_progress`	Work has begun.
`fulfilled`	The commitment has been completed.
`partially_fulfilled`	Some scope was completed; some remains.
`abandoned`	The committing organization has discontinued.
`expired`	The target completion date passed without fulfillment.

Transition with POST /v0/commitments/status (mirrors the need status endpoint).

Step 3 — Attest engagement (optionally fulfilling a commitment)

When engagement happens on the ground, the acting organization files an engagement attestation. To link the attestation to a prior commitment, include fulfillsCommitmentId:

Code
 
curl -X POST https://api.global.church/v0/engagement-claims/submit \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/audio-scripture-org",
    "orgName": "Audio Scripture Org",
    "claimedByEmail": "[email protected]",
    "peopleGroupRop3": "115648",
    "peopleGroupRog3": "KAZ",
    "peopleGroupName": "Kazakh, Northern",
    "countryCode": "KZ",
    "countryName": "Kazakhstan",
    "engagementAccelerators": ["SRA-AUD"],
    "description": "Initial 50-chapter recording deployed via SD-card distribution.",
    "fulfillsCommitmentId": "6a91f5c4-3e22-4db8-bc34-7e9af0124567"
  }'

Code
 
{ "claimId": "f1d4ab1a-7c80-4f6c-a4f5-2b9d4c0a5678", "status": "active" }

Any organization may attest fulfillment of any commitment. The attestation records who attested (claimedByEmail and orgUri); the commitment retains its own committing organization.

Walking the chain in SPARQL

After the three calls above, this query returns the full Need → Commitment → Attestation triangle:

Code
 
PREFIX gc:   <https://ontology.global.church/core#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?need ?needDesc ?cmt ?cmtDesc ?att ?attDesc
WHERE {
  GRAPH <https://data.global.church/needs/> {
    ?need a gc:Need ;
          gc:needDescription ?needDesc .
  }
  GRAPH <https://data.global.church/commitments/> {
    ?cmt a gc:FulfillmentCommitment ;
         gc:concernsNeed ?need ;
         gc:commitmentDescription ?cmtDesc .
  }
  GRAPH <https://data.global.church/engagement-claims/> {
    ?att a gc:EngagementAttestation ;
         gc:fulfillsCommitment ?cmt ;
         gc:claimDescription ?attDesc .
  }
}

Listing and filtering

GET /v0/needs, GET /v0/commitments, and GET /v0/engagement-claims all support filtering by orgUri and status. GET /v0/commitments additionally accepts concernsNeedId to find every commitment responding to a particular need. See the API Reference for the full parameter list per endpoint.