> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Claim link

> POST /v1/platform-users/claim-link: a 24-hour link that lets a person take their managed account into their own CabalSpy ID.

Creates a link that lets the person behind a [platform user](https://docs.cabalspy.xyz/cabalspy-id/white-label.md) take their managed account into their own, normal CabalSpy ID. Send the link to the user, for example from their settings page on your platform.

The link is valid for 24 hours and can be used once. Each call creates a new link.

## What a claim does

The person opens the link on `id.cabalspy.xyz`, signs in with their own CabalSpy ID and confirms. Then:

* their **payment-verified** wallets move to their own CabalSpy ID; unverified wallets do not move,
* X and Telegram move along if their CabalSpy ID has none yet; their theses and Trade Feed move along too,
* your instance keeps access to them as a user, `csid_id` becomes the id of their own account, and `claimed` turns true,
* you receive the `platform_user.claimed` [webhook](https://docs.cabalspy.xyz/cabalspy-id/webhooks.md#white-label-events) with the previous csid\_id.

From then on the person manages the account themselves. Calls that change it return `account_claimed`, and [deleting](https://docs.cabalspy.xyz/cabalspy-id/platform-users-delete.md) the user only removes the link to your platform.

The claim page refuses the claim when the person's account would end up with more than 5 Solana or 5 EVM wallets, or when their account is already linked to another of your users. They see the reason on the page.

> [!NOTE]
>
> Claim links are off when your instance is marked `white_label` and on otherwise, until you set `claim_links` in the [settings](https://docs.cabalspy.xyz/cabalspy-id/platform-users-settings.md).

## Body

**external\_id** `string` *required*

Your id of the user. Alternatively pass csid\_id.

**return\_url** `string`

Where the person goes back after the claim. Must be on one of your instance's verified domains, registered origins or redirect URIs (https), or `http://localhost`.

## Usage Example

```bash cURL theme={null}
curl -X POST "https://api-id.cabalspy.xyz/v1/platform-users/claim-link" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "user_8412", "return_url": "https://app.example.com/settings"}'
```

```python Python theme={null}
import requests

r = requests.post("https://api-id.cabalspy.xyz/v1/platform-users/claim-link",
                  json={"external_id": "user_8412", "return_url": "https://app.example.com/settings"},
                  headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["data"]["url"])
```

```javascript JavaScript theme={null}
const res = await fetch("https://api-id.cabalspy.xyz/v1/platform-users/claim-link", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ external_id: "user_8412" }),
});
const { data } = await res.json();
console.log(data.url, data.expires_at);
```

## Response

**external\_id** `string`

Your id of the user.

**url** `string`

The claim link, on `https://id.cabalspy.xyz/claim/...`.

**expires\_at** `string`

When the link expires, 24 hours after it was created.

```json Response theme={null}
{
  "success": true,
  "data": {
    "external_id": "user_8412",
    "url": "https://id.cabalspy.xyz/claim/Zt3kV9...",
    "expires_at": "2026-10-27T08:04:11Z"
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-26T08:04:11Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | external\_id missing. |
| 400 | invalid\_return\_url | return\_url is not on one of your instance's sites. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | claim\_disabled | Claim links are off for your instance. |
| 404 | platform\_user\_not\_found | No user with this id in your instance. |
| 409 | account\_claimed | The account was already claimed. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |

See [Errors](https://docs.cabalspy.xyz/cabalspy-id/errors.md) for the full list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.