# Customizing the Completion Screen

Control what a user sees after connecting a LinkedIn account through a connection session embedded in your product: the completion screen, redirect and messages.

> The API Reference is also the SDK and CLI reference. Consecutive code fences marked `tab=HTTP`, `tab=Node`, `tab=Python` and `tab=CLI` are the same call on each surface (a fence marked `tab=HTTP,CLI` is the same text for both), and a block between `:::surface <names>` and `:::` applies only to the surfaces it names. Identifiers in the text are written as in Node and in HTTP JSON (camelCase); the Python SDK spells methods, parameters and result attributes in snake_case (`sendMessage` → `send_message`, `reconnectionLink` → `reconnection_link`), while names inside HTTP JSON stay camelCase.

After the user finishes logging into LinkedIn, the connection page shows a completion screen. The optional `completion` object accepted by `accounts.createConnectionSession` and `accounts.createReconnectionSession` controls what happens there – which is what you need when the connection page is embedded into your own product. Every field is optional, and omitting `completion` entirely keeps the default behavior.

:::surface node,python,cli
The SDKs and the CLI create connection and reconnection sessions without `completion`, so everything on this page is available only through the HTTP endpoints.
:::

```json
{
  "completion": {
    "limits": { "mode": "ask" },
    "successUrl": "https://app.acme.com/connected?session={SESSION_ID}",
    "failureUrl": "https://app.acme.com/failed?session={SESSION_ID}"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `limits.mode` | `string` | How account limits are handled: `ask` (default), `defaults`, or `skip`. Ignored on reconnection, which never changes an account's limits |
| `button.text` | `string` | Label of a custom button shown on the completion screen (1–40 characters). Not allowed together with `successUrl` |
| `button.url` | `string` | Where that button leads. `https` only, no placeholders |
| `successUrl` | `string` | Redirect the user here after a successful connection, without any click |
| `failureUrl` | `string` | Redirect the user here when the session ends in `error` or `expired` |

**Limits modes:**

| Mode | Behavior |
|------|----------|
| `ask` | Default. The user is shown the limits editor and chooses the values themselves |
| `defaults` | Recommended limits are applied automatically, the editor is not shown |
| `skip` | No limits are configured and the editor is not shown. The account runs without limits until you set them via [`limits.set`](/docs/admin-limits) |

**Default button:** sessions created through this API do not show the "Continue to platform" button, because it leads to the Linked API dashboard, which your users have no access to. Instead, the completion screen tells the user the account is connected and the tab can be closed. To send the user somewhere, pass either `button` (they leave by clicking) or `successUrl` (they leave immediately). Passing both is rejected: with an instant redirect the button would never be visible.

**Placeholders:** `successUrl` and `failureUrl` may contain placeholders that are substituted before the redirect. Values are URL-encoded.

| Placeholder | Available in | Value |
|-------------|--------------|-------|
| `{SESSION_ID}` | `successUrl`, `failureUrl` | UUID of the connection session |
| `{ACCOUNT_ID}` | `successUrl` | UUID of the account that was just connected |
| `{ERROR_TYPE}` | `failureUrl` | Error type of the failed session, empty for `expired` |

Any other placeholder, an unbalanced brace, or a non-`https` URL is rejected with `invalidRequestPayload` when the session is created – not later, when the user is already on the page.

**When the redirect happens:**

- `successUrl` fires after the limits step. With `mode: "ask"` that means after the user saves or skips the limits editor; with `defaults` or `skip` it fires as soon as the connection succeeds.
- `failureUrl` covers the `error` and `expired` statuses. Sessions you cancel yourself through `accounts.cancelConnectionSession` do not redirect, and neither does an invalid or unknown session link, since there is no configuration to read for it.

> **Do not rely on the redirect for fulfillment.** The user may close the tab or lose connectivity before it happens. Treat arriving on `successUrl` as a hint and confirm the real outcome with `accounts.getConnectionSession`.

**Examples:**

Fully embedded – no questions asked, the user is returned to your product in both outcomes:

```bash
curl -X POST https://api.linkedapi.io/admin/accounts.createConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "completion": {
      "limits": { "mode": "defaults" },
      "successUrl": "https://app.acme.com/connected?session={SESSION_ID}&account={ACCOUNT_ID}",
      "failureUrl": "https://app.acme.com/failed?session={SESSION_ID}&error={ERROR_TYPE}"
    }
  }'
```

Keep the limits editor, but finish with your own button instead of an automatic redirect:

```bash
curl -X POST https://api.linkedapi.io/admin/accounts.createConnectionSession \
  -H "Content-Type: application/json" \
  -H "linked-api-token: linked_your_token_here" \
  -d '{
    "completion": {
      "limits": { "mode": "ask" },
      "button": { "text": "Back to Acme", "url": "https://app.acme.com/accounts" }
    }
  }'
```