Claim a connection code

Turn the one-time code a partner generated into a connection, so you can act for that partner.

POST{BASE_URL}/connections/claim

Claims the connection code a partner generated for you and handed over, and returns the resulting connection. Requires a provider key; needs no partner header — the code names the partner.

Claiming is idempotent for you: claiming a code you already claimed, before it expires, answers 200 with the same connection. Retry a timed-out claim with the same code.

Body

codestringrequired: The code as the partner pasted it, such as LCC-7K2M-9QXT-4VBN-H3WP. Case, spaces and hyphens do not matter, and the LCC- prefix is optional.

Response

dataobjectrequired: The connection, with status ACTIVE.

Status codes#

Status	Code	Meaning
`201`	—	Claimed. The connection is new.
`200`	—	You had already claimed this code, and it has not expired: the same connection, with the message `Already claimed — this is the same connection.`
`400`	—	The body has no `code` string, or it is blank or longer than 64 characters.
`403`	`provider_key_required`	A partner key made the call.
`404`	`connection_code_invalid`	The code is unknown, expired or already used, belongs to another provider, or its connection was disconnected. One answer for all of them.
`429`	`connection_claim_rate_limited`	More than 20 claims in 15 minutes with this key.

Side effects#

The partner's connection becomes active: from now on your calls for it are accepted, within its effective scopes, and your webhook endpoints receive its events.

curl -X POST "$LOCALOY_BASE_URL/connections/claim" \
  -H "Authorization: Bearer $LOCALOY_PROVIDER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "LCC-7K2M-9QXT-4VBN-H3WP" }'

Response · 201

{
  "success": true,
  "message": "Connected. Send this partner's id in X-Localoy-Partner-Id to act for them.",
  "data": {
    "id": "cm7c0nn3ct10n00000000001",
    "partnerId": "cm1partnerid000000000000001",
    "partner": { "name": "Sultan's Dine" },
    "status": "ACTIVE",
    "scopes": ["REGISTRATION", "UPDATE", "INVENTORY"],
    "grantedScopes": ["REGISTRATION", "UPDATE", "INVENTORY"],
    "modules": ["EVENT", "DINING"],
    "connectedAt": "2026-09-27T09:14:02.518Z",
    "scopesGrantedAt": "2026-09-27T09:12:40.107Z",
    "pausedAt": null,
    "revokedAt": null,
    "lastCallAt": null
  }
}

Response · 404

{
  "success": false,
  "message": "That connection code is not valid. Ask the partner for a new one — a code works once, for 15 minutes.",
  "code": "connection_code_invalid",
  "requestId": "3f0c9f8e-6a1d-4f5e-9b1a-2f1c0d9e7a41"
}