API reference

Every Givebear Connect endpoint, with request and response shapes generated from the live OpenAPI spec.

The Givebear Connect API is a REST API over HTTPS. The base URL is https://givebear.io/api/v1. Every endpoint returns JSON.

Authenticate every request with a bearer credential: an org API key (gb_live_...) or an OAuth access token (gba_...). Each credential is scoped to one organization. See authentication for how to issue and scope credentials, and the quickstart for your first request.

Download OpenAPI spec Postman collection

curl "https://givebear.io/api/v1/donations" \
  -H "Authorization: Bearer gb_live_..."

Pagination

List endpoints accept three query parameters:

limit: page size, 1 to 100 (default 25).
cursor: the opaque next_cursor from a previous response.
updated_since: an ISO-8601 lower bound on creation time.

Every list response is the same envelope. Read next_cursor and pass it back as cursor until has_more is false.

{
  "data": [],
  "has_more": true,
  "next_cursor": "eyJ..."
}

The @givebear/connect client walks pages for you with listAll().

Errors

A non-2xx response returns this envelope. The type is a stable machine-readable code (for example unauthorized, insufficient_scope, rate_limited, invalid_request); message is human-readable.

{
  "error": {
    "type": "insufficient_scope",
    "message": "This credential is missing the `donations:read` scope"
  }
}

Endpoints

The reference below is generated from the OpenAPI spec, so it always matches what the API validates and returns. Each operation lists its parameters, request body, response schema, and copy-pasteable samples in cURL, @givebear/connect, JavaScript, Python, Go, PHP, Ruby, Java, and C#.

For event names and signature verification, see webhooks. For the API version policy, see versioning.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/donations", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "donation",      "amount_cents": 0,      "net_amount_cents": 0,      "currency": "string",      "recurring": true,      "refund_status": "string",      "refunded_amount_cents": 0,      "dispute_status": "string",      "donor_name": "string",      "donor_email": "string",      "fund_id": "string",      "fund_name": "string",      "campaign_id": "string",      "contact_id": "string",      "source": "string",      "source_id": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/donations/string", {  method: "GET"})

{  "id": "string",  "object": "donation",  "amount_cents": 0,  "net_amount_cents": 0,  "currency": "string",  "recurring": true,  "refund_status": "string",  "refunded_amount_cents": 0,  "dispute_status": "string",  "donor_name": "string",  "donor_email": "string",  "fund_id": "string",  "fund_name": "string",  "campaign_id": "string",  "contact_id": "string",  "source": "string",  "source_id": "string",  "created_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/donors", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "donor",      "email": "string",      "first_name": "string",      "last_name": "string",      "phone": "string",      "city": "string",      "state": "string",      "postal_code": "string",      "country": "string",      "source": "string",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/donors/string", {  method: "GET"})

{  "id": "string",  "object": "donor",  "email": "string",  "first_name": "string",  "last_name": "string",  "phone": "string",  "city": "string",  "state": "string",  "postal_code": "string",  "country": "string",  "source": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/payouts", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "payout",      "amount_cents": 0,      "currency": "string",      "status": "string",      "arrival_date": "2019-08-24T14:15:22Z",      "created": "2019-08-24T14:15:22Z",      "description": "string",      "statement_descriptor": "string"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/payouts/string", {  method: "GET"})

{  "id": "string",  "object": "payout",  "amount_cents": 0,  "currency": "string",  "status": "string",  "arrival_date": "2019-08-24T14:15:22Z",  "created": "2019-08-24T14:15:22Z",  "description": "string",  "statement_descriptor": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

published?boolean

Only published (true) or only draft (false) events.

upcoming?true

Only events starting at or after now.

Value in

true

Response Body

`application/json`

fetch("https://example.com/events", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "event",      "slug": "string",      "title": "string",      "description": "string",      "location": "string",      "event_format": "string",      "online_meeting_url": "string",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "timezone": "string",      "pricing_mode": "string",      "price_cents": 0,      "pwyw_min_cents": 0,      "pwyw_suggested_cents": 0,      "capacity": 0,      "allow_waitlist": true,      "requires_approval": true,      "published": true,      "published_at": "2019-08-24T14:15:22Z",      "registration_opens_at": "2019-08-24T14:15:22Z",      "registration_closes_at": "2019-08-24T14:15:22Z",      "campaign_id": "string",      "fund_id": "string",      "ticket_types": [        {          "id": "string",          "object": "event_ticket_type",          "name": "string",          "description": "string",          "price_cents": 0,          "capacity": 0,          "sort_order": 0,          "is_active": true        }      ],      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/events/string", {  method: "GET"})

{  "id": "string",  "object": "event",  "slug": "string",  "title": "string",  "description": "string",  "location": "string",  "event_format": "string",  "online_meeting_url": "string",  "starts_at": "2019-08-24T14:15:22Z",  "ends_at": "2019-08-24T14:15:22Z",  "timezone": "string",  "pricing_mode": "string",  "price_cents": 0,  "pwyw_min_cents": 0,  "pwyw_suggested_cents": 0,  "capacity": 0,  "allow_waitlist": true,  "requires_approval": true,  "published": true,  "published_at": "2019-08-24T14:15:22Z",  "registration_opens_at": "2019-08-24T14:15:22Z",  "registration_closes_at": "2019-08-24T14:15:22Z",  "campaign_id": "string",  "fund_id": "string",  "ticket_types": [    {      "id": "string",      "object": "event_ticket_type",      "name": "string",      "description": "string",      "price_cents": 0,      "capacity": 0,      "sort_order": 0,      "is_active": true    }  ],  "created_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

status?string

Filter to one status: pending, confirmed, cancelled, checked_in, waitlisted, or refunded.

Response Body

`application/json`

fetch("https://example.com/events/string/registrations", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "registration",      "event_id": "string",      "ticket_type_id": "string",      "attendee_name": "string",      "attendee_email": "string",      "attendee_phone": "string",      "status": "string",      "quantity": 0,      "attendee_names": [        "string"      ],      "amount_paid_cents": 0,      "refunded_cents": 0,      "refunded_at": "2019-08-24T14:15:22Z",      "checked_in_at": "2019-08-24T14:15:22Z",      "source": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/campaigns", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "campaign",      "slug": "string",      "name": "string",      "description": "string",      "goal_cents": 0,      "is_active": true,      "start_date": "2019-08-24T14:15:22Z",      "end_date": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/funds", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "fund",      "name": "string",      "description": "string",      "type": "string",      "goal_cents": 0,      "published": true,      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Response Body

`application/json`

fetch("https://example.com/organization", {  method: "GET"})

{  "id": "string",  "object": "organization",  "name": "string",  "slug": "string",  "legal_name": "string",  "contact_email": "string",  "website": "string",  "tax_id": "string",  "created_at": "2019-08-24T14:15:22Z"}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount_cents*integer

Range50 <= value

fund_id*string

Length1 <= length

donor_email*string

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Formatemail

donor_name*string

Length1 <= length

recurring?boolean

recurring_interval?integer

Range0 < value

recurring_frequency?string

Value in

"day"
"week"
"month"
"year"

cover_fees?boolean

campaign_id?string

Response Body

`application/json`

const body = JSON.stringify({  "amount_cents": 50,  "fund_id": "string",  "donor_email": "[email protected]",  "donor_name": "string"})fetch("https://example.com/payment-intents", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{  "object": "payment_intent",  "client_secret": "string",  "payment_intent_id": "string",  "publishable_key": "string",  "stripe_account_id": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

fund_id?string

campaign_id?string

preset_amounts_cents?array<>

Items1 <= items <= 6

default_amount_cents?integer

Range50 <= value

amounts_locked?boolean

default_recurring?boolean

recurring_locked?boolean

donor?

Response Body

`application/json`

const body = JSON.stringify({})fetch("https://example.com/embed-sessions", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{  "id": "string",  "object": "embed_session",  "session_token": "string",  "organization_id": "string",  "embed_url": "string",  "expires_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

components*array<>

Items1 <= items

Response Body

`application/json`

const body = JSON.stringify({  "components": [    "donations"  ]})fetch("https://example.com/component-sessions", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{  "id": "string",  "object": "component_session",  "token": "string",  "organization_id": "string",  "components": [    "donations"  ],  "expires_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Response Body

`application/json`

fetch("https://example.com/webhooks", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "webhook_endpoint",      "url": "string",      "description": "string",      "events": [        "donation.created"      ],      "created_at": "2019-08-24T14:15:22Z"    }  ]}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url*string

Formaturi

description?string

events*array<>

Items1 <= items

Response Body

`application/json`

const body = JSON.stringify({  "url": "http://example.com",  "events": [    "donation.created"  ]})fetch("https://example.com/webhooks", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})

{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "donation.created"  ],  "created_at": "2019-08-24T14:15:22Z",  "secret": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/webhooks/string/rotate-secret", {  method: "POST"})

{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "donation.created"  ],  "created_at": "2019-08-24T14:15:22Z",  "secret": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Query Parameters

limit?integer

Page size, 1-100 (default 25).

Range1 <= value <= 100

cursor?string

Opaque cursor from a previous response's next_cursor.

updated_since?string

ISO-8601 lower bound on creation time.

Formatdate-time

Response Body

`application/json`

fetch("https://example.com/webhooks/string/deliveries", {  method: "GET"})

{  "data": [    {      "id": "string",      "object": "webhook_delivery",      "event_type": "donation.created",      "event_id": "string",      "status": "pending",      "attempts": 0,      "last_response_status": 0,      "last_error": "string",      "next_attempt_at": "2019-08-24T14:15:22Z",      "delivered_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "has_more": true,  "next_cursor": "string"}

{  "error": {    "type": "string",    "message": "string"  }}

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/webhooks/string", {  method: "GET"})

{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "donation.created"  ],  "created_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

url?string

Formaturi

description?string|null

events?array<>

Items1 <= items

Response Body

`application/json`

const body = JSON.stringify({})fetch("https://example.com/webhooks/string", {  method: "PATCH",  headers: {    "Content-Type": "application/json"  },  body})

{  "id": "string",  "object": "webhook_endpoint",  "url": "string",  "description": "string",  "events": [    "donation.created"  ],  "created_at": "2019-08-24T14:15:22Z"}

{  "error": {    "type": "string",    "message": "string"  }}

{  "error": {    "type": "string",    "message": "string"  }}

Live testing is off for write endpoints. There is no sandbox yet, so a call here would create real data. Use the code samples to call this endpoint from your app.

Authorization

bearerAuth

AuthorizationBearer <token>

An org API key (gb_live_...) or OAuth access token (gba_...).

In: header

Path Parameters

id*string

Response Body

`application/json`

fetch("https://example.com/webhooks/string", {  method: "DELETE"})

{  "id": "string",  "deleted": true}

{  "error": {    "type": "string",    "message": "string"  }}

Was this page helpful?

200application/json

200application/json

404application/json

200application/json

200application/json

404application/json

200application/json

200application/json

404application/json

200application/json

200application/json

404application/json

200application/json

404application/json

200application/json

200application/json

200application/json

200application/json

400application/json

200application/json

400application/json

200application/json

400application/json

200application/json

201application/json

400application/json

200application/json

404application/json

200application/json

404application/json

200application/json

404application/json

200application/json

400application/json

404application/json

200application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`