> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endaoment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner Journey

> Server-to-server partner flow for users, funds, settled donations, and grants.

## 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](./overview) 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](./integration-patterns#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](./integration-patterns) and the [Partner Endpoints](/developers/api/partner-endpoints/provision-user) API reference.

## Journey

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

Retrieve a partner fund: [Get fund by ID](/developers/api/partner-endpoints/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`.

```bash theme={null}
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](./integration-patterns#partner-auth-options). Example using API key + impersonation header:

```bash theme={null}
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](/developers/api/partner-endpoints/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.

```bash theme={null}
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](/developers/api/partner-endpoints/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](./going-to-prod)