# Create a native mobile survey session (/api-reference/survey-channels/createMobileSurveySession)

`POST /v1/retention/mobile-survey-sessions`

Base URL: `https://api.bitelio.com`

The merchant backend must authenticate the customer and bind their device before requesting a session. Requires retention:view and retention:edit, active mobile permission and an accepted MOBILE_API delivery. contactId must match that exact delivery. receiptToken stays on the server. The returned token expires after 15 minutes (or invitation expiry), is bound to deviceId and is revoked by permission updates. Never put a secret key in the app. 120 requests/project/minute. See /guides/native-surveys.

## Request body

- `deliveryId`: string (uuid) (required)
- `contactId`: string (required)
- `receiptToken`: string (uuid) (required)
- `deviceId`: string (required)

Example:

```json
{
  "deliveryId": "string",
  "contactId": "string",
  "receiptToken": "string",
  "deviceId": "string"
}
```

## Responses

### `200` — Device-scoped session

- `sessionToken`: string (required)
- `expiresAt`: string (date-time) (required)
- `capabilities`: object (required)
  - `nativeQuestions`: enum (true)
  - `conditionalQuestions`: enum (true)
  - `resume`: enum (true)
  - `choice`: enum (true)
  - `multipleChoice`: enum (true)
  - `rating`: enum (true)
  - `explicitSubmission`: enum (true)

```json
{
  "sessionToken": "string",
  "expiresAt": "2026-10-24T08:42:45.094Z",
  "capabilities": {
    "nativeQuestions": true,
    "conditionalQuestions": true,
    "resume": true,
    "choice": true,
    "multipleChoice": true,
    "rating": true,
    "explicitSubmission": true
  }
}
```

### `400` — Invalid input or unavailable survey

### `401` — Secret API key required

### `403` — Required project permission missing

### `404` — Session, permission or survey unavailable

### `429` — Rate limit exceeded; Retry-After gives seconds

### `503` — Rate limiter temporarily unavailable

## Example request

```bash
curl -X POST 'https://api.bitelio.com/v1/retention/mobile-survey-sessions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"deliveryId":"string","contactId":"string","receiptToken":"string","deviceId":"string"}'
```