# Register explicit customer permission for mobile follow-up (/api-reference/survey-channels/registerRetentionMobilePermission)

`POST /v1/retention/mobile-permissions`

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

Merchant server only: derive contactId from the authenticated app customer, verify device permission and retain their explicit consent. Scope SURVEY permits surveys; RETENTION also permits help, recommendations and offers. No existing survey permission is silently expanded. Requires retention:view and retention:edit; shares the project channel API rate limit. Optional timeZone is the IANA zone reported by the authenticated customer device, for example America/New_York; never infer it from IP or country. It adjusts configured contact hours for 90 days, then falls back to the store zone. It does not expand consent or create a schedule.

## Request body

- `contactId`: string (required)
- `scope`: enum ("SURVEY" | "RETENTION") (required)
- `consent`: boolean (required)
- `timeZone`: string — Optional device-declared IANA time zone, captured only after explicit permission and tenant/customer verification.

Example:

```json
{
  "contactId": "string",
  "scope": "SURVEY",
  "consent": false
}
```

## Responses

### `200` — Success

- `id`: string (required)
- `status`: string (required)
- `scope`: enum ("SURVEY" | "RETENTION") (required)

```json
{
  "id": "string",
  "status": "string",
  "scope": "SURVEY"
}
```

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

### `401` — Secret API key required

### `403` — Required project permission is missing

### `429` — Project rate limit exceeded. Retry-After identifies the wait in seconds.

### `503` — Rate limiter temporarily unavailable; retry later.

## Example request

```bash
curl -X POST 'https://api.bitelio.com/v1/retention/mobile-permissions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"contactId":"string","scope":"SURVEY","consent":false}'
```