Partner Journey - Endaoment

Outcome

A tech-platform partner can provision users, create partner-managed funds, record settled donations, submit grants after custodian settlement, and report missing organizations—all without a donor OAuth login flow.

When

Use this track instead of the standard OAuth journey when you integrate as an Endaoment tech-platform partner with API key credentials.

Auth

Most server-to-server partner endpoints require x-api-key. Acting-user context depends on the step — see Partner auth options. POST /v1/funds/partner is an exception: it also accepts a registered OAuth user Bearer token or partner OIDC bearer without x-api-key. For this partner journey, use x-api-key throughout.

Header	When
`x-api-key`	Most partner endpoints (and this journey’s examples)
`x-endaoment-user-id`	Optional acting-user path for fund creation and settled pledges
`partnerUserIdentifier` (body)	Alternative acting-user path when partner inflow routes are enabled
`Authorization: Bearer`	Optional partner OIDC path for `POST /v1/funds/partner`

See Integration Patterns and the Partner Endpoints API reference.

Journey

Step	Outcome	Endpoint	API reference
1	Partner user exists	`POST /v1/auth/partner/users`	Provision user
2	Partner fund exists	`POST /v1/funds/partner`	Create fund
3	Settled donation recorded	`POST /v1/donation-pledges/partner/cash-settled` or `.../stock-settled`	Cash · Stock
4	Grant submitted after settlement	`POST /v1/transfers/partner/grant-submissions`	Submit settled grant
5	Missing org reported	`POST /v1/missing-org-reports/tech-platform`	Submit missing org report

Retrieve a partner fund: Get fund by ID.

Step 1: Provision user

Inputs: partnerUserIdentifier (your stable partner-side user id — 16–64 printable ASCII characters), user profile fields, and required address.

curl -X POST "https://api.dev.endaoment.org/v1/auth/partner/users" \
  -H "x-api-key: $PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerUserIdentifier": "550e8400-e29b-41d4-a716-446655440002",
    "firstName": "Alex",
    "lastName": "Donor",
    "email": "alex@example.com",
    "address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105"
    }
  }'

Persist: response.id as the Endaoment user UUID for later x-endaoment-user-id use.

Step 2: Create partner fund

The acting user must already have saved identity from Step 1. Pick an auth path from Partner auth options. Example using API key + impersonation header:

curl -X POST "https://api.dev.endaoment.org/v1/funds/partner" \
  -H "x-api-key: $PARTNER_API_KEY" \
  -H "x-endaoment-user-id: $ENDAOMENT_USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner Giving Fund",
    "description": "Partner-managed DAF",
    "partnerAccountIdentifier": "550e8400-e29b-41d4-a716-446655440001"
  }'

Required: name, partnerAccountIdentifier (16–64 printable ASCII characters). See Create fund for the full schema. Persist: Fund id.

Step 3: Record settled donation

Call after the donation has already settled on your platform. Provide acting-user context via x-endaoment-user-id or body partnerUserIdentifier (when partner inflow routes are enabled).

Asset	Endpoint
Cash	`POST /v1/donation-pledges/partner/cash-settled`
Stock	`POST /v1/donation-pledges/partner/stock-settled`

Step 4: Submit partner grant

Server-to-server grant intake after inbound custodian transfer has settled. No donor Bearer token or acting-user header required.

curl -X POST "https://api.dev.endaoment.org/v1/transfers/partner/grant-submissions" \
  -H "x-api-key: $PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "...": "see API reference" }'

Step 5: Report missing org

For nonprofits not yet in Endaoment’s database: POST /v1/missing-org-reports/tech-platform API reference: Submit missing org report

Common mistakes

Using donor OAuth flows for partner-only operations
Omitting required address on user provisioning
Using partner identifiers shorter than 16 characters
Creating a partner fund before the acting user has provisioned PII
Assuming x-endaoment-user-id is always required on settled pledges (body partnerUserIdentifier is an alternative)
Submitting partner grants before custodian settlement completes

Next: Going to Production

​Outcome

​When

​Auth

​Journey

​Step 1: Provision user

​Step 2: Create partner fund

​Step 3: Record settled donation

​Step 4: Submit partner grant

​Step 5: Report missing org

​Common mistakes