---
title: "Partner API: Event Portals | Stayker Developers"
description: Integrate hotel booking portals with Stayker. API authentication, organizer accounts, event requests, retries, error handling, and credential security.
---

[Skip to API reference](https://events.stayker.com/developers/partner-api/event-portals#reference)

[STAYKER](https://stayker.com)

Build. Book. Connect.

Stayker developer documentation

# Your events. A hotel booking portal for every one.

Connect your platform to Stayker. Send organizer and event details, receive a hotel booking link, and keep each organizer's events together.

Partner API · v1REST / JSONServer-to-server

**Credentials are delivered separately.**This reference contains examples only. Use the approved endpoint, environment, and key supplied through your existing developer onboarding.

**Event portals**[Overview](https://events.stayker.com/developers/partner-api/event-portals#overview) [Getting connected](https://events.stayker.com/developers/partner-api/event-portals#getting-connected) [Authentication](https://events.stayker.com/developers/partner-api/event-portals#authentication) [Create or update an event](https://events.stayker.com/developers/partner-api/event-portals#events) [Request fields](https://events.stayker.com/developers/partner-api/event-portals#fields) [Updates and cancellation](https://events.stayker.com/developers/partner-api/event-portals#updates) [Reliability and errors](https://events.stayker.com/developers/partner-api/event-portals#reliability) [Credential security](https://events.stayker.com/developers/partner-api/event-portals#security) [Integration acceptance](https://events.stayker.com/developers/partner-api/event-portals#acceptance) [Stripe Connect payouts](https://events.stayker.com/developers/partner-api/event-portals#stripe-connect) [Support and versioning](https://events.stayker.com/developers/partner-api/event-portals#support)

Create a hotel booking portal from the event data you already manage.

API version **v1** · Reference updated **19 November 2026**

## Overview

Send the organizer, event name, dates, and venue coordinates from your backend. Stayker creates or updates the event under the organizer's Client account and returns a hotel booking portal link for your attendees.

The account hierarchy is **Partner → Organizer (Client) → Event**. Each stable organizer ID maps to its own Client beneath your Partner account. The API credential determines the Partner; callers cannot choose a different Partner in a request.

This reference covers event-to-portal integrations enabled for your account. It does not describe the separate 1Stay/MCP search-and-book API. Use the integration profile and credentials assigned during your existing developer onboarding.

## Getting connected

Your onboarding contact supplies your approved **API base URL, environment, expected Partner identity, assigned scope, and credential expiry**. The bearer key is delivered separately through the agreed secure method. An application or onboarding form submission is not proof that production access has been approved.

Keep the base URL configurable. It includes `/api/partner/v1`; do not append that path twice. The hostname below is a nonfunctional documentation example:

```
export STAYKER_API_BASE='https://api.example.invalid/api/partner/v1'
# Load STAYKER_API_KEY from your server-side secret manager.
```

Use only the environment supplied to you. Do not infer a sandbox hostname or reuse a production key in test systems. Successful requests to a production endpoint create or update real records; agree on test IDs and cleanup before your first write.

## Authentication

All API calls are server-to-server over HTTPS:

```
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/json
```

### Check your access

```
curl --fail-with-body --connect-timeout 10 --max-time 30 \
  "$STAYKER_API_BASE/access" \
  -H "Authorization: Bearer $STAYKER_API_KEY" \
  -H 'Accept: application/json'
```

`GET /access` returns HTTP 200 and these fields. Values below are illustrative; compare your response to the identity supplied during onboarding.

```
{"partner_id":123,"scope":"<assigned-scope>"}
```

Stop if the Partner or scope differs from your assignment. This call verifies access without creating an event. There is no OAuth exchange or automatic token-refresh endpoint in this API.

## Create or update an event

```
PUT /events/{externalEventId}
```

`externalEventId` is your stable event identifier. `client_org_id` is your stable organizer identifier. Both are case-sensitive, 1–191 characters, must begin with an ASCII letter or digit, and may then contain ASCII letters, digits, `_`, `.`, `:`, or `-`.

Save the following as `event.json`. Replace the sample data with your approved event details and future dates before sending:

```
{
  "client_org_id": "org-12345",
  "org": {"name": "Example Sports Association"},
  "name": "Example Spring Cup",
  "start_date": "2027-03-18",
  "end_date": "2027-03-20",
  "venue_name": "Example Sports Park, Charlotte, NC",
  "venue_lat": 35.2271,
  "venue_lng": -80.8431,
  "status": "active"
}
```

```
curl --fail-with-body --connect-timeout 10 --max-time 30 \
  -X PUT "$STAYKER_API_BASE/events/event-67890" \
  -H "Authorization: Bearer $STAYKER_API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-binary @event.json
```

Creation and updates both return **HTTP 200**:

```
{
  "stayker_event_id": 12345,
  "booking_url": "https://booking.example.invalid/example-event/widget?lat=35.2271&long=-80.8431&checkin=2027-03-17&checkout=2027-03-21&place=Example%20Sports%20Park&currency=USD&adults=2&room=1",
  "status": "active"
}
```

The URL above is illustrative. Store the actual `stayker_event_id` and `booking_url` against your event. Use the returned URL unchanged in your **Book hotels** link. Do not build a URL from the event name, replace its hostname, or attach your key. No iframe is required for this flow.

## Request fields

| Field | Requirement |
| --- | --- |
| `client_org_id` | Required stable organizer ID. All events for the same organizer use the same ID. |
| `org.name` | Required on the first event for an organizer. Nonblank, maximum 191 characters. Once the organizer exists, `org` may be omitted. If supplied, `org` must include a name. |
| `org.contact_email` | Optional valid email, maximum 191 characters. It is not an identity or ownership key. |
| `name` | Required event name, maximum 191 characters. |
| `start_date` | Required `YYYY-MM-DD`. A newly created event cannot start in the past. |
| `end_date` | Required `YYYY-MM-DD`, on or after the start date. |
| `venue_name` | Required venue/location text, maximum 191 characters. |
| `venue_lat` | Required numeric latitude, −90 to 90. |
| `venue_lng` | Required numeric longitude, −180 to 180. An address alone is insufficient. |
| `status` | `active` or `cancelled`. Defaults to `active` if omitted; explicitly send it on every update. |

The initial hotel search uses **one day before event start through one day after event end**, USD, two adults, and one room. The example event defaults to check-in 17 March and check-out 21 March.

### Organizer ownership

Different organizer IDs create separate Client accounts even when their contact emails match. Reusing an organizer ID reuses its Client. Existing Client profile details are preserved; event requests do not rename an existing Client or change its contact email.

An existing event cannot be moved to another organizer through this endpoint. Attempting reassignment returns 422. Contact your onboarding contact for ownership corrections. Do not invent a new ID to work around an ownership error.

## Updates and cancellation

Use the same PUT endpoint and identifiers for every update. Send all required fields; this is not a partial PATCH. Serialize changes to an event because the API does not expose a version/conflict token.

To cancel an event, resend its complete payload with `"status":"cancelled"`. The response reports `cancelled`; its portal becomes unavailable. Remove the booking link from your event page. **Event cancellation does not cancel existing hotel reservations.** Handle reservation changes through the separate reservation support process.

Sending `"status":"active"` re-enables the event. Retrying an obsolete active payload after cancellation can therefore reopen it; retry the latest intended state only.

## Reliability and errors

The event PUT is idempotent by Partner and stable external event ID: identical retries reuse the same event and organizer mapping. No separate idempotency header is required. This guarantee applies to this provisioning endpoint, not to separate hotel-booking or payment APIs.

Set connection and response timeouts. For network failures or retryable server errors, use bounded exponential backoff with jitter, keep the same IDs and intended payload, and stop after a finite retry budget. A timeout does not prove that nothing was saved.

The routes are configured for **30 requests per minute**. Start below that combined rate and honor `Retry-After` and rate-limit response headers. Do not assume separate quotas for each key or endpoint, or attempt to bypass limits with parallel workers.

| HTTP | Meaning and action |
| --- | --- |
| 200 | Success; consume the JSON response. |
| 401 | Missing, invalid, expired, or unusable credential. Check configuration and contact Stayker. Do not retry unchanged indefinitely. |
| 403 | Authorization or ownership no longer permits the operation. Stop and contact Stayker. |
| 422 | Invalid input or forbidden organizer reassignment. Read `errors` and correct the request. |
| 429 | Rate limited. Honor `Retry-After`, then retry with backoff. |
| 503 | Provisioning unavailable. Back off; contact Stayker if persistent. |
| Other 5xx / timeout | Retry within your configured budget, preserving IDs and intended state. Escalate persistent failures. |

Validation response shape; message text may vary:

```
{
  "message": "Validation failed.",
  "errors": {
    "client_org_id": ["An existing event cannot be reassigned to another organizer."]
  }
}
```

Send `Accept: application/json`. Check the HTTP status and content type before parsing; an intermediary can return a non-JSON error. Handle field errors without relying on exact English message text.

## Credential security

Keep API calls on your backend. Store keys in a managed secret store with access limited to the integration service and authorized operators. Separate production and test configuration. Use HTTPS with certificate validation enabled; never use `curl -k`.

Never put keys in browser code, mobile bundles, URLs, analytics, screenshots, source control, HubSpot forms, support tickets, or shared collections. Redact authorization headers from logs, traces, and error reports. A documentation page is not a credential-delivery channel.

Record the assigned owner, environment, permissions, and expiry without recording the raw key in general CRM notes. Arrange replacement before expiry; validate the new key with `/access`, then coordinate retirement of the old key. Do not assume overlapping validity or self-service rotation is available.

If a key or access link is exposed, stop distributing it and contact Stayker promptly for revocation and replacement. Removing the visible copy alone does not make the credential safe again. Share only redacted incident details.

These practices follow the principles in the [OWASP REST Security](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html) and [Secrets Management](https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html) guidance. They are integration requirements and recommendations, not a claim of a security certification.

## Integration acceptance

Before enabling the integration for organizers:

1. Verify `/access` returns your assigned Partner and scope.
2. Create an agreed test event and verify its returned portal opens for the expected event, dates, and location.
3. Retry the same request and confirm the same event ID and URL.
4. Create a second event for a different organizer and have Stayker verify separate Client ownership.
5. Verify invalid input and organizer reassignment are rejected.
6. Cancel test events and confirm their portals become unavailable.
7. Record the tested environment, date, and outcomes. Validate inventory, room selection, and checkout separately if those are part of your launch acceptance.

Do not make a real hotel reservation as an API smoke test without an agreed booking and cancellation plan.

## Next step: Stripe Connect payouts

**Separate onboarding step — not yet available through this API.**The event-to-hotel-portal integration does not activate payouts. Stayker will confirm availability after end-to-end validation and provide the supported onboarding instructions separately.

The planned flow uses Stripe Connect Express for each organizer organization receiving earnings and a separate account for the Partner receiving its own share. Creating an organizer's Client account in Stayker does not create or verify its Stripe payout account.

1. An authorized organizer administrator opens the Stayker-hosted earnings panel from your platform. The planned flow does not require a separate Stayker login.
2. The organizer chooses **Collect your earnings** and completes Stripe's onboarding form. The Partner completes its own onboarding for its own earnings.
3. Business verification and payout bank details are supplied through Stripe's onboarding interface. Never include them in event API requests, HubSpot forms, email, or support tickets.
4. Stayker verifies the account's payout eligibility before treating onboarding as complete. Returning from the form alone is not confirmation that payouts are enabled.

Your platform must restrict organizer onboarding to administrators authorized for that exact organization. API credentials stay on your backend; they must never be passed to the embedded panel. Do not build against unannounced onboarding endpoints or reuse another organization's payout account.

The payout schedule, revenue shares, reserves, and any applicable fees are governed by your agreed commercial terms. This reference does not activate transfers or promise a payout date. Background: [Stripe embedded onboarding](https://docs.stripe.com/connect/embedded-onboarding).

## Support and versioning

Contact the Stayker representative assigned in your existing developer onboarding. Provide the UTC timestamp, environment, method/path, HTTP status, external organizer/event IDs, and a redacted response. Include a request identifier if one was returned. Exclude credentials, payment data, and unnecessary personal information.

This document covers the assigned `/api/partner/v1` event-portal contract. Handle additional response fields gracefully and rely on the documented fields. Confirm endpoint or contract changes with Stayker before switching environments or changing production configuration.

Stayker · Partner API documentationReference updated 19 November 2026 · [Privacy](https://stayker.com/legal/privacy)