# Create a deep link

`POST https://app.shuttleglobal.com/c/api/instances/{instance_key}/deep_links`

Create a new deep link. All fields are nested under the `deep_link` field.
See the deep link types section for available deep links and their specific parameters.

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Request body (`application/json`), required

- `deep_link` (object)
  - `type` (string, required): Type of deep link to create: * `gateway-setup`: Merchant Setup (onboarding) * `dashboard`: Merchant View One of: `gateway-setup`, `dashboard`.
  - `context` (object): Type-specific parameters that vary based on the deep link type: For type: `gateway-setup` (Onboarding) * `processor`: Limit onboarding to a single processor (e.g., "STRIPE") * `processor_filter`: Array of allowed processors (e.g., ["STRIPE", "SQUARE"]) * `theme`: UI customization options including: - Font settings (baseFontSize, baseFontFamily) - Colors (backgroundColor, headerBackground) - Layout (baseBorderRadius, rowHeight) - Full theme options documented in UI Components guide For type: `dashboard` (Merchant View) * `mode`: Section to display — "enquiry" or "setup" * `action`: View to display: - "view_account": Show account details - "view_contract": Show contract details - "view_transaction": Show transaction details - "view_payment_method": Show payment method details - "localisation": Show localisation settings (requires mode "setup") * `id`: ID of object to view (use this OR alt_key) * `alt_key`: Alternative key of object (use this OR id) * `menu`: Menu display type: - "normal": Standard menu - "banner": Banner style menu with logo - "hidden": No menu * `favicon`: URL to PNG favicon when opened in window * `menu_logo`: URL to PNG logo for banner menu (max 120x20px) * `return_url`: URL to return to when logo clicked (banner menu) * `features`: Turn individual Merchant View actions (refunds, captures, account editing, contract amendments) on or off for this session, overriding the defaults set on the application. See [Merchant View Options](/platforms/embedded-payments/activity-view-options/)
    - `processor` (string): For gateway-setup, use onboarding for a single processor only (e.g., "STRIPE")
    - `processor_filter` (array of string): For gateway-setup, filter available processors (e.g., ["STRIPE", "SQUARE"])
    - `theme` (object): UI theme customization options including font settings, colors, and layout. See UI Components guide for full list of theme properties.
    - `mode` (string): Section of the merchant view to display One of: `enquiry`, `setup`.
    - `action` (string): Specific view to display in merchant view One of: `view_account`, `view_contract`, `view_transaction`, `view_payment_method`, `localisation`.
    - `id` (string): ID of object to view in merchant view (use this OR alt_key)
    - `alt_key` (string): Alternative key of object to view (use this OR id)
    - `menu` (string): Type of menu to display in merchant view One of: `normal`, `banner`, `hidden`.
    - `favicon` (string): URL to PNG favicon when merchant view opened in window
    - `menu_logo` (string): URL to PNG logo for banner menu (max 120x20px recommended)
    - `return_url` (string): URL to return to when logo clicked in banner menu
    - `features` (object): For merchant view, overrides the Merchant View options set on the application (Developer Portal, Developer tab, Merchant View), for this deep link only. Each key is an option -- `account_edit`, `comments`, `manual_capture`, `moto_payment`, `moto_tokenise`, `payment_method_edit`, `recurring`, `recurring_edit`, `recurring_edit_in_place`, `refund`, `refund_offline` -- and each value is `"TRUE"` or `"FALSE"`. An option you omit keeps the application default; an option never set anywhere is enabled. Disabling an option removes the control from the UI entirely. For what each option does, see [Merchant View Options](/platforms/embedded-payments/activity-view-options/)
  - `user` (object)
    - `alt_key` (string, required): Your primary key for the logged in user
    - `name` (string): Name of the logged in user
  - `session` (object)
    - `teams` (array of string): Teams the user belongs to
  - `ip_address` (string): IP address of the merchant
  - `expiry_seconds` (integer): Time in seconds this deep link is active

## Responses

### 200: Created deep link

```json
{
  "deep_link": {
    "type": "gateway-setup",
    "context": {
      "processor": "string",
      "processor_filter": [
        "string"
      ],
      "theme": {},
      "mode": "enquiry",
      "action": "view_account",
      "id": "string",
      "alt_key": "string",
      "menu": "normal",
      "favicon": "string",
      "menu_logo": "string",
      "return_url": "string",
      "features": {
        "refund": "FALSE",
        "manual_capture": "FALSE",
        "account_edit": "FALSE"
      }
    },
    "user": {
      "alt_key": "string",
      "name": "string"
    },
    "session": {
      "teams": [
        "string"
      ]
    },
    "ip_address": "string",
    "expiry_seconds": 900,
    "id": "string"
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorised: the API key is missing or not valid

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request POST \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/deep_links \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>' \
  --header 'Content-Type: application/json' \
  --data '{
  "deep_link": {
    "type": "gateway-setup",
    "context": {
      "features": {
        "refund": "FALSE",
        "manual_capture": "FALSE",
        "account_edit": "FALSE"
      }
    },
    "expiry_seconds": 900
  }
}'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/createdeeplink/