Overview

Accounts, Lookup, Search, Inventory, Content & Booking 35.7.1

Partner Integrator API

Authenticated, usage-metered access to bookable travel inventory for API integrators. Query properties, availability and rates programmatically at scale over gRPC, calling the wink.partner.v1 services below. Requests are counted and rate-limited per account: a free tier applies until you subscribe to the metered paid tier. See the Partner API pricing & SLA page for current limits, per-request pricing and terms.

Every call carries two gRPC metadata headers:

Header	Value
`authorization`	`Bearer <token>` — an OAuth2 client-credentials token, see Authentication
`managing-entity-id`	The account you are calling on behalf of

Authorization is per account: the account named in managing-entity-id is checked for INVENTORY:READ, and metered usage is billed to it. Omit the header and the call fails with INVALID_ARGUMENT; name an account you do not hold INVENTORY:READ on and it fails with PERMISSION_DENIED.

The account is a header rather than a request field so that it is known before the request body is read — which is what lets quota and rate-limit checks reject a call without decoding it. Request messages therefore have no account field, and setting one is not possible.

Generating a client

You call this API with a generated gRPC client, not with curl. Wink publishes the schema two ways:

Server reflection — the server describes itself, so grpcurl, Postman and Insomnia discover the schema at runtime with nothing to download. Reflection needs the same bearer token as any other call.
The .proto files, if you would rather vendor the schema and generate ahead of time.

# Reflection describes the schema and needs only the token — it is not account-scoped.
grpcurl -H "authorization: Bearer $WINK_TOKEN" partner.wink.travel:443 list

# Every actual call additionally needs the account header.
grpcurl -H "authorization: Bearer $WINK_TOKEN" \
        -H "managing-entity-id: $WINK_ACCOUNT_ID" \
        -d '{"urlName": "bangkok-thailand", "type": "CITY"}' \
        partner.wink.travel:443 wink.partner.v1.Lookup/Get

Generating a Wink gRPC client walks through it with our schema. For the language-specific toolchain, see the official gRPC quick starts.

Connection lifecycle

These are server settings you cannot discover from the schema, and each one will disconnect a client that guesses wrong. Configure your channel to match.

Setting	Value	What it means for you
Minimum keepalive interval	20s	Do not send HTTP/2 keepalive pings more often than every 20 seconds. A faster client is disconnected with `GOAWAY(ENHANCE_YOUR_CALM)`. Most gRPC clients default to 10s or less, so this usually needs setting explicitly.
Pings without active calls	allowed	You may keep an idle connection alive with pings; you do not have to hold a call open.
Server keepalive	60s	We ping you every 60 seconds to detect a dead peer. Answer them — most clients do automatically.
Maximum connection age	30m (±10%)	We send a graceful `GOAWAY` roughly every half hour and you should reconnect. This is normal, not an error: it is how traffic rebalances as we scale. Do not alert on it.
Concurrent streams per connection	200	Beyond this, open a second connection.

The jitter on connection age is deliberate — it stops every client in a fleet reconnecting in lockstep.

# Go, for example
grpc.WithKeepaliveParams(keepalive.ClientParameters{
    Time:                30 * time.Second,  // >= our 20s minimum
    PermitWithoutStream: true,
})

This is a gRPC API, not a REST API. Each operation is listed at the HTTP/2 path the transport really uses (/package.Service/Method, always POST), and the schemas are the proto3 JSON mapping of each message — so the contract is readable and model generation is correct. But these endpoints are not callable with an ordinary HTTP client: a real request body is a length-prefixed protobuf frame. Use a generated gRPC client, or the .proto schema published via server reflection.

Errors

Failures arrive as a gRPC status code in the response trailers, not as an HTTP status code:

Status	Meaning
`INVALID_ARGUMENT`	The request was malformed, or a required field was missing.
`UNAUTHENTICATED`	Bearer token missing, expired or invalid.
`PERMISSION_DENIED`	The token is valid but lacks the required grant on the account.
`NOT_FOUND`	No record matched (only on operations that resolve a single record).
`RESOURCE_EXHAUSTED`	Quota exceeded. Carries `retry-after` and `x-ratelimit-*` trailers — back off by the value given.

Contact

[email protected]

Information

OpenAPI version: 3.0.1

Authentication

oauth2ClientCredentials

Every endpoint is protected with OAuth2 client credentials. Create an Application in your account to obtain a clientId and clientSecret, then exchange them for a short-lived bearer token.

1. Request an access token

POST to the Token URL below with Content-Type: application/x-www-form-urlencoded and a body of grant_type=client_credentials (optionally scope=<space-separated scopes>). Send your credentials as HTTP Basic auth: Authorization: Basic base64(clientId + ":" + clientSecret).

2. Call the API

Pass the returned token on every request: Authorization: Bearer <access_token>.

Tokens carry only the scopes granted to your Application — request the least privilege you need. There is no interactive authorize step and no refresh token for this flow; request a new token when the current one expires.

Security scheme type: oauth2

Flow type: clientCredentials

Token URL: https://iam.wink.travel/oauth2/token

Scopes:

inventory.read - View your inventory & rates.
inventory.write - Create and update your inventory & rates.
inventory.remove - Delete your inventory & rates.