Partner Journey

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`	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

When a donor wants a nonprofit you cannot find on Endaoment, report it with your API key: POST /v1/missing-org-reports

201 returns a report id. Store it. A second report for the same EIN is a separate report.
409 means the nonprofit is already on Endaoment. Use existingOrgId from the response instead of waiting.

Then read the outcome with the report id. This call needs no API key: GET /v1/missing-org-reports/{id} status is submitted while Endaoment reviews it. approved comes with resolvedOrgId, the nonprofit to grant to. rejected comes with rejectionReason, which you can show the donor. POST /v1/missing-org-reports/tech-platform is deprecated. It takes the same body and gives the same answers, so move to POST /v1/missing-org-reports when you next touch this code. API reference: Submit missing org report · Get missing org report status

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)
Correcting a settled donation by re-sending it with the same idempotencyKey and a fixed amount (settled pledges cannot be amended, see Conflicts on write routes)
Submitting partner grants before custodian settlement completes

Next: Going to Production

About

Quickstart

Endpoints

Smart Contracts

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

​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

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