Global.Church Developer Portal
Global.Church API

Needs

Endpoint:https://api.global.church

List needs

GET
https://api.global.church
/v0/needs

Returns at:Need instances from GraphDB (https://data.global.church/needs/). Optional filters: orgUri, status, limit.

List needs › query Parameters

  • orgUristring

    Filter by declaring organization URI.

  • statusstring · enum

    Filter by need status.

    Enum values:
    open
    partially_met
    met
    withdrawn
  • limitinteger · min: 1 · max: 200

    Max rows to return (default 50, max 200).

List needs › Headers

  • Authorizationstring · required

    The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List needs › Responses

List of needs

  • needsobject[] · required
  • totalinteger · required

Submit need

POST
https://api.global.church
/v0/needs

Creates a new at:Need declaration for an organization. The person must be a steward of the organization in the Home, which is checked at request time. Send the signed-in person's Home sign-in token in the x-home-id-token header; the gateway verifies it and refuses the request with 401 without a valid one. The acting person is the token's subject: userId is set from it and any userId sent in the body is ignored.

Submit need › Headers

  • Authorizationstring · required

    The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

  • x-home-id-tokenstring · required

    The signed-in person's sign-in token (the ES256 id_token issued by the Home). The gateway verifies its signature, issuer, audience and expiry, and takes the acting person from its subject.

Submit need › Request Body

  • orgUristring · required

    GraphDB URI of the declaring organization

  • orgNamestring · required

    Display name of the organization

  • needDescriptionstring · required

    Free-text description of the need

  • acceleratorsstring[] · minItems: 1 · required

    Phases of Engagement Toolkit accelerator domain codes — the twelve top concepts of poe:EngagementAcceleratorScheme (PRA Prayer, SRA Scripture/Resource Access, VIS Vision Casting, MNE Multi-node Engagement, MOB Mobilization/Sending, COL Collaborative Engagement, COM Meeting Needs/Compassion, CTX Critical Contextualization, RCI Research/Cultural Insights, TRN Training/Equipping, MUL Multiplying Efforts, MKT Marketplace Involvement). Since ontology v0.51.0 these are the only accepted values; the former XXX-YYY function codes are rejected with 400. What an organization is equipped to do is classified separately on the organization (gc:hasOrganizationalCapability), never here.

    Enum values:
    PRA
    SRA
    VIS
    MNE
    MOB
    COL
    COM
    CTX
  • concernsPeopleGroupRop3string[]

    Optional — ROP3 codes of people groups the need concerns.

  • concernsCountryCodestring[]

    Optional — ISO alpha-2 country codes where the need exists.

Submit need › Responses

Need created

  • needIdstring · uuid · required
  • statusstring · enum · required
    Enum values:
    open

CORS preflight for needs

OPTIONS
https://api.global.church
/v0/needs

CORS preflight for needs › Responses

No content

No data returned

Update need status

POST
https://api.global.church
/v0/needs/status

Transitions a at:Need between open / partially_met / met / withdrawn. The person must be a steward of the need's owning organization in the Home, which is checked at request time. No state-machine enforcement — any status is reachable from any status. Send the signed-in person's Home sign-in token in the x-home-id-token header; the gateway verifies it and refuses the request with 401 without a valid one. The acting person is the token's subject: userId is set from it and any userId sent in the body is ignored.

Update need status › Headers

  • Authorizationstring · required

    The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

  • x-home-id-tokenstring · required

    The signed-in person's sign-in token (the ES256 id_token issued by the Home). The gateway verifies its signature, issuer, audience and expiry, and takes the acting person from its subject.

Update need status › Request Body

  • needIdstring · uuid · required
  • statusstring · enum · required
    Enum values:
    open
    partially_met
    met
    withdrawn

Update need status › Responses

Status updated

  • needIdstring · uuid · required
  • statusstring · required

CORS preflight for need status

OPTIONS
https://api.global.church
/v0/needs/status

CORS preflight for need status › Responses

No content

No data returned
PartnersCommitments