LocaloyDevelopers
Technology Providersv1

Provider API reference

The endpoints only Technology Providers call, and the partner-scoped endpoints you share with partners' own keys.

Technology Providers call the same JSON REST API as partners, at the same base URL, authenticated with a provider key. Responses use the same envelope.

Base URL#

https://api-host.localoy.app/api/v1/open-network/v1

Sandbox and production share the base URL; the key decides the environment. Paths below are relative to it.

Two kinds of endpoint#

  • Provider endpoints — connections and webhooks. They act for your company, not for a partner, and ignore X-Localoy-Partner-Id. A partner key gets 403 provider_key_required.
  • Partner-scoped endpoints — catalogue, bookables and payments, documented in the Open Network API reference. You call them for one partner: send its partnerId in X-Localoy-Partner-Id, and stay within the connection's effective scopes.

Errors any call can return#

StatusCodeMeaning
401open_network_key_invalidThe key is missing, malformed, unknown, revoked or expired.
403provider_suspendedLocaloy has suspended your company.
429—Rate limited. See Limits.

Each endpoint's own codes are on its page, and all of them are in Errors.

Provider endpoint
curl "$LOCALOY_BASE_URL/connections?limit=25" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY"
Partner-scoped endpoint
curl "$LOCALOY_BASE_URL/catalog/items" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY" \
  -H "X-Localoy-Partner-Id: $LOCALOY_PARTNER_ID"
GET /connections · 200
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "cm7c0nn3ct10n00000000001",
        "partnerId": "cm1partnerid000000000000001",
        "partner": { "name": "Sultan's Dine" },
        "status": "ACTIVE",
        "…": "…"
      }
    ],
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Provider endpoints#

MethodPathDescription
GET/pingVerify a key. With X-Localoy-Partner-Id, also see that partner's connection and effective scopes. See Verifying a key.
POST/connections/claimClaim a partner's connection code.
GET/connectionsList your connections.
GET/connections/{partnerId}Retrieve your connection with one partner.
GET/webhooks/eventsList event types and the delivery policy.
GET/webhooksList your webhook endpoints.
POST/webhooksCreate an endpoint.
GET/webhooks/{id}Retrieve an endpoint.
PATCH/webhooks/{id}Update an endpoint.
DEL/webhooks/{id}Delete an endpoint.
GET/webhooks/{id}/secretReveal an endpoint's signing secret.
POST/webhooks/{id}/secretRotate an endpoint's signing secret.
POST/webhooks/{id}/testSend a signed test event.
GET/webhooks/deliveriesList deliveries.
GET/webhooks/deliveries/{id}Retrieve a delivery.
POST/webhooks/deliveries/{id}/replayReplay a delivery.

Partner-scoped endpoints#

Send X-Localoy-Partner-Id on every one. They are documented in the Open Network API reference; the last column is what differs when you call them.

MethodPathScopeFor a provider
POST/catalog/itemsREGISTRATIONThe item is tagged with your connection. An externalId the partner or another integration uses answers 409 open_network_item_managed_elsewhere.
GET/catalog/itemsINVENTORYOnly the items you created for the partner.
GET/catalog/items/{externalId}INVENTORYOnly your items; any other answers 404.
PATCH/catalog/items/{externalId}UPDATEOnly your items.
DEL/catalog/items/{externalId}UPDATEOnly your items.
GET/bookablesINVENTORYOnly bookables in your modules; linking another answers 404.
GET/payments/sessions/{id}PAYMENTOnly sessions whose order is in your modules.
POST/payments/sessions/{id}/resultPAYMENTAs above.
POST/payments/sessions/{id}/refundPAYMENTAs above.

Each of them can also answer 400 partner_id_required, 404 connection_not_found, 403 connection_paused and 403 open_network_scope_required. See The partner header. GET /health needs no key.