# Partner API
> Source: /api-reference/partner/overview
> API for property staff and hotel management systems to manage loyalty programs, fulfillments and guest intelligence

The Partner API gives property staff, hotel management systems, and partner
integrations access to loyalty program configuration, the Action Center,
member and reservation lookup, guest intelligence, and partner pages — all
scoped to your organization.

## Base URL [#base-url]

Every partner route is served under `/v1`. The version is part of the path, so
it is already included in the base URLs below.

| Environment | Base URL |
|---|---|
| Production | `https://api-prd.cf.journey.com/v1` |
| Sandbox (staging) | `https://api-stg.cf.journey.com/v1` |

Staging is the partner sandbox and is paired with the WorkOS staging
environment, so staging credentials are separate from production credentials.

```
https://api-prd.cf.journey.com/v1/partner/fulfillments/search
```

## Authentication [#authentication]

Send your partner API key in the `X-API-Key` header:

```http
X-API-Key: jny_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  Earlier versions of this page showed `Authorization: Bearer jny_…` for API
  keys. That is not what the server reads today and it returns `401`. Use
  `X-API-Key`. Accepting the key as a Bearer token is the target behaviour and
  is tracked on the [Partner authentication](/api-reference/partner/authentication)
  page.
</Warning>

Operator-driven surfaces (an actual person signed in to HXP) authenticate with
that operator's WorkOS access token instead:

```http
Authorization: Bearer <workos-access-token>
```

Core resolves the organization, permissions and venue reach from the verified
token. See [Partner authentication](/api-reference/partner/authentication) for
the full model, including what is live today and what is coming soon.

## Scopes [#scopes]

Each route requires one permission string. These are the real values the server
checks — the earlier `FULFILLMENTS.READ` style names were internal constant
names, not wire values.

| Area | Scopes |
|---|---|
| Loyalty programs and tiers | `partner:loyalty:programs:read`, `partner:loyalty:programs:write` |
| Benefits and entitlements | `partner:loyalty:benefits:read`, `partner:loyalty:benefits:write` |
| Arrivals | `partner:arrivals:read`, `partner:arrivals:write` |
| Fulfillments | `partner:fulfillments:read`, `partner:fulfillments:write` |
| Reservations | `partner:reservations:read` |
| Guests and members | `partner:guests:read` |
| Guest PII (invites, Windfall) | `partner:guests:read` **and** `partner:guests:pii:read` |
| Teammate venue reach | `partner:access:read`, `partner:access:write` |
| Theme kits | `partner:theme-kits:read`, `partner:theme-kits:manage` |
| Custom domains | `partner:custom-domains:read`, `partner:custom-domains:manage` |
| Partner pages | `partner:pages:read`, `partner:pages:manage` |
| Point multipliers | `partner-details:read` |
| Offer code pools | `offers:codes:read`, `offers:codes:write` |

<Note>
  The PII-bearing routes (`/partner/vguests/guest-invites` and
  `/partner/windfall/*`) require **both** `partner:guests:read` and
  `partner:guests:pii:read`. Holding only the PII scope is not enough.
</Note>

## Conventions [#conventions]

<ParamField header="Idempotency-Key" type="string" required>
  Required on every `POST`, `PUT`, `PATCH` and `DELETE`. Replaying the same key
  with the same body returns the original response plus
  `X-Idempotent-Replay: true`. The same key with a different body returns
  `409`. Keys longer than 255 characters return `400`.
</ParamField>

<ParamField header="X-Emulate-Org-Id" type="string">
  Journey staff only. Optionally paired with `X-Emulate-Property-Ids`. Emulation
  only ever narrows access; it never grants permissions.
</ParamField>

- **IDs are external.** Requests and responses use external ids (UUID v7, ULID
  or HMS external id). The two exceptions are `memberId` on
  `GET /partner/windfall/members/:memberId` and `inviteId` on the guest-invite
  routes, which are internal integers.
- **Organization scope comes from your credential.** A partner credential
  ignores `?organizationId=`; only Journey staff with global scope may send it.
- **`404` means "not found or not yours".** The two cases are deliberately
  indistinguishable.
- **Responses are additive-only.** New fields appear over time; ignore fields
  you do not recognise.

## Errors [#errors]

Every error uses the same shape:

```json
{
  "type": "validation_error",
  "timestamp": "2026-10-09T18:22:41.218Z",
  "code": "ambiguous_credentials",
  "message": "Conflicting credentials were supplied.",
  "details": {
    "reason": "Authorization and X-API-Key carried different credentials."
  }
}
```

| Status | Meaning |
|---|---|
| 400 | Validation failed, or conflicting credentials (`ambiguous_credentials`) |
| 401 | Missing, invalid, expired or revoked credential |
| 403 | Authenticated, but missing the required scope or organization |
| 404 | Not found, or outside your organization and venue reach |
| 409 | Conflicts with current state, or an idempotency key was reused |

## Webhooks [#webhooks]

There are no outbound partner webhooks today. Poll
`GET /partner/arrivals` and `GET /partner/fulfillments/pending` for the Action
Center feeds. See [Partner webhooks](/api-reference/partner/webhooks) for what
is planned.

## Core features [#core-features]

<CardGroup cols={2}>
  <Card title="Fulfillment Management" icon="gift" href="/api-reference/partner/fulfillments/search">
    Search, verify, approve, reject, and mark fulfillments as completed
  </Card>
  <Card title="Member Lookup" icon="user-search" href="/api-reference/partner/members/list">
    Search and retrieve member profiles scoped to your organization
  </Card>
  <Card title="Windfall Intelligence" icon="brain" href="/api-reference/partner/windfall/overview">
    PMS guest hash lookup and member identity intelligence
  </Card>
  <Card title="Partner Pages" icon="layout-template" href="/api-reference/partner/pages">
    Partner-managed CMS pages, SEO, themes and custom domains
  </Card>
  <Card title="Authentication" icon="key-round" href="/api-reference/partner/authentication">
    Keys, scopes, idempotency and the WorkOS organization key rollout
  </Card>
  <Card title="API explorer" icon="terminal" href="/api-reference/partner/explorer/scope/get-scope">
    All 110 endpoints with an interactive playground, generated from the spec.
    Response schemas are still being filled in upstream.
  </Card>
  <Card title="Core Partner Insights" icon="sparkles">
    Tenant-safe guests, members, reservations, folios and governed disclosure
  </Card>
</CardGroup>