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

# Link sessions

> One time through Link: its status, its result in your app, and how your server confirms it.

export const Screen = ({name, alt, caption, wide = false}) => {
  const style = wide ? {
    width: '100%'
  } : {
    width: '280px',
    maxWidth: '100%'
  };
  return <figure style={{
    margin: '1.5rem 0',
    textAlign: 'center'
  }}>
      <img className="block dark:hidden" src={`/images/sdk/${name}-light.webp`} alt={alt} style={{
    ...style,
    margin: '0 auto',
    borderRadius: '12px',
    border: '1px solid rgba(128, 128, 128, 0.25)'
  }} />
      <img className="hidden dark:block" src={`/images/sdk/${name}-dark.webp`} alt={alt} style={{
    ...style,
    margin: '0 auto',
    borderRadius: '12px',
    border: '1px solid rgba(128, 128, 128, 0.25)'
  }} />
      {caption ? <figcaption style={{
    marginTop: '0.5rem',
    fontSize: '0.875rem',
    opacity: 0.7
  }}>{caption}</figcaption> : null}
    </figure>;
};

A **link session** is one time through Link: your user adds a charger, changes its network, sets it up or reconnects it. Link opens it with a client secret when the hosted flow starts, and the SDK returns its id as `sessionId` when Link closes. Your server reads it with [Get a link session](/sdk/api/get-link-session).

## Statuses

| `status` | Meaning |
| - | - |
| `opened` | Your user is in Link. |
| `completed` | Link finished: `devices` and `charger_ids` list the chargers it finished. |
| `abandoned` | Your user left, declined, or the flow failed: see `abandon_reason`. |
| `expired` | It wasn't finished within 6 hours of opening. |

`abandon_reason` is `cancelled` (your user closed Link), `consent_declined` (they chose **Not now** on the consent screen) or `error`. With `error`, `error.code` says why, for your logs, for example `wifi_join_failed` or `charger_unreachable`. New codes may be added: don't branch on them.

## The result in your app and the truth on your server

When Link closes, your app gets a result with:

| Field | |
| - | - |
| `status` | `success`, `cancelled` or `error` |
| `action` | The action the link session did |
| `sessionId` | The link session, or `null` when Link closed before one started |
| `devices` | `{ type, id }` for each device Link reported; on `success`, the ones it finished |
| `error` | On `error`: a `code` and an optional `message`. See [Errors](/sdk/errors). |

The result is for your app's screens. Before your server relies on it, it reads the link session itself:

1. Your app sends `sessionId` to your server.
2. Your server calls `GET /sdk/v1/link-sessions/{id}` and checks that `external_user_id` is the signed-in user.
3. When `status` is `completed`, it stores the chargers in `devices`.

A link session your server didn't hear about (your app was killed, for example) is still there: you can also list a user's chargers with `GET /sdk/v1/chargers?external_user_id=…`.

## Chargers that belong to someone else

When your user adds a charger that is already connected to another Plugchoice account, Link can **claim** it for them. Plugchoice emails the current owner to approve it within 7 days. While the charger is online and not open to the public, your user can also prove they're at the charger by plugging in a car.

<Screen name="claim" alt="Link waiting for the charger's owner, with the option to prove you're at the charger by plugging in" />

A claim can succeed after the link session has ended. The charger then appears at the link session's site. `claims` in the link session shows each claim's `status`:

| `status` | Meaning |
| - | - |
| `pending` | Waiting for the owner, or for your user to plug in. |
| `approved`, `proven`, `released` | It succeeded: the owner agreed, your user plugged in, or the owner didn't answer for a charger that had been offline for 30 days. `charger_id` is set. |
| `rejected`, `expired`, `withdrawn` | It didn't: the owner said no, 7 days passed, or the link session was abandoned. |

While a claim is `pending`, check the link session again later, for example once a day, or list the user's chargers.


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