# 10DLC Application Admin API

This page describes the endpoints for managing your [10DLC](10dlc.md) settings
through the [Messaging Application Admin API](application-admin-api.md). It allows you to create individual settings for networks (for example, SIP domains) within your application, or a single set of settings for the whole application.

Each application is identified by a `cloudId`, which is part of every endpoint URL.

A network is a logical group of users identified by a `networkId` within an
application. Its exact meaning depends on the deployment:

- In SIP-based deployments, it commonly corresponds to a SIP domain, although one
  network may span multiple domains.
- In non-SIP deployments, it may represent another tenant, service, or endpoint
  group.

Using these endpoints you can create, read, update and delete the 10DLC settings
for your application.

## Authentication

See [Authentication](application-admin-api.md#authentication) and [Getting access](application-admin-api.md#getting-access).

All 10DLC endpoints require a valid API key; a missing or invalid key returns `401 Unauthorized`.

## Base URL

See [API base URL](application-admin-api.md#api-base-url).

The 10DLC endpoints share this base URL:

```
https://api-us.messaging.acrobits.cz/app-admin-api/{cloudId}/ten-dlc-settings
```

- `cloudId` (path, required) — your application identifier.
- `networkId` (query parameter, optional) — identifies the specific network within your
  application that the 10DLC settings apply to. See [Identifying 10DLC settings](#identifying-10dlc-settings-in-requests).

## Identifying 10DLC settings in requests

10DLC settings are treated as resources (persistent entities). They are identified by the combination of your `cloudId` (from the
URL) and an optional `networkId` (query parameter). The settings `id` is never used on this API, so that clients can address the desired settings directly in a single request, without having to determine or persist their IDs.

There are two modes, controlled by the `mapping` field and the presence of
`networkId`:

| Mode | `mapping` value | `networkId` query param | Meaning |
| --- | --- | --- | --- |
| Per cloud ID | `PER_CLOUD_ID` | must be omitted | A single set of settings for the whole application. |
| Per network ID | `PER_NETWORK_ID` | required | One set of settings per network. `networkId` selects exactly one. |

Rules:

- When `mapping` is `PER_NETWORK_ID`, the `networkId` query parameter is
  mandatory. If it is missing, the request fails with `400 Bad Request`.
- When `networkId` is omitted, operations target the single per-cloud-ID set of
  settings.

## Endpoints

### Create 10DLC settings

```
POST /app-admin-api/{cloudId}/ten-dlc-settings?networkId={networkId}
```

Request body:

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mapping` | string | yes | | `PER_CLOUD_ID` or `PER_NETWORK_ID` — whether the settings apply to the whole application or to a single network. See [Identifying 10DLC settings](#identifying-10dlc-settings-in-requests). |
| `brand` | string | yes | | Business or service name shown in the automated welcome and help messages (see [Automated Message Templates](10dlc.md#automated-message-templates)) for the SMS channels of user accounts within the `networkId` (or `cloudId`). |
| `contactNumber` | string | no | `null` | Contact phone number. |
| `contactEmail` | string | no | `null` | Contact email. |
| `contactOther` | string | no | `null` | Other contact information. |
| `enabled` | boolean | no | `false` | Whether the settings are enabled. |
| `customWelcomeText` | string | no | `null` | Custom welcome/opt-in confirmation text. |
| `customOptOutText` | string | no | `null` | Custom opt-out text. |
| `customOptInText` | string | no | `null` | Custom opt-in text. |
| `customHelpText` | string | no | `null` | Custom help text. |

Notes:

- At least one contact (`contactEmail`, `contactNumber` or `contactOther`) must be provided,
  unless both `customWelcomeText` and `customHelpText` are supplied.

Example request:

```bash
curl -X POST \
  "https://api-us.messaging.acrobits.cz/app-admin-api/MY_CLOUD_ID/ten-dlc-settings?networkId=my-network" \
  -H "x-app-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "mapping": "PER_NETWORK_ID",
        "brand": "My Brand",
        "contactNumber": null,
        "contactEmail": "support@example.com",
        "contactOther": null,
        "enabled": true,
        "customWelcomeText": null,
        "customOptOutText": null,
        "customOptInText": null,
        "customHelpText": null
      }'
```

Responses:

- `201 Created` with the created settings in the response body (see [Settings response structure](#settings-response-structure-used-in-create-get-and-update)).
- `400 Bad Request` if the body is invalid (for example, missing `mapping` or `brand`, or no contact provided), or if `mapping` is `PER_NETWORK_ID` and `networkId` is missing.

### Get 10DLC settings

```
GET /app-admin-api/{cloudId}/ten-dlc-settings?networkId={networkId}
```

Returns the settings identified by `cloudId` + `networkId`.

Example request:

```bash
curl -X GET \
  "https://api-us.messaging.acrobits.cz/app-admin-api/MY_CLOUD_ID/ten-dlc-settings?networkId=my-network" \
  -H "x-app-api-key: <your-api-key>"
```

Responses:

- `200 OK` with the settings in the response body (see [Settings response structure](#settings-response-structure-used-in-create-get-and-update)).
- `404 Not Found` if no settings exist for the given `cloudId` + `networkId`.

### Update 10DLC settings

```
PUT /app-admin-api/{cloudId}/ten-dlc-settings?networkId={networkId}
```

Updates the settings identified by `cloudId` + `networkId`. This is a **full
update**: the request body replaces all settings, so you must send every field
you want to keep. Any non-required field omitted from the body is leaving the current persisted value intouched.

Request body:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `brand` | string | yes | Business or service name shown in the automated welcome and help messages (see [Automated Message Templates](10dlc.md#automated-message-templates)) for the SMS channels of user accounts within the `networkId` (or `cloudId`). |
| `contactNumber` | string | no | Contact phone number. |
| `contactEmail` | string | no | Contact email. |
| `contactOther` | string | no | Other contact information. |
| `enabled` | boolean | true | Whether the settings are enabled. |
| `customWelcomeText` | string | no | Custom welcome/opt-in confirmation text. |
| `customOptOutText` | string | no | Custom opt-out text. |
| `customOptInText` | string | no | Custom opt-in text. |
| `customHelpText` | string | no | Custom help text. |

Notes:

- `mapping` is fixed at creation and cannot be changed by an update.
- When `enabled` is omitted from the update body, the settings' current `enabled` value is left unchanged.
- Body validation is the same as for [Create 10DLC settings](#create-10dlc-settings).

Example request (all fields are sent, because the update replaces all settings):

```bash
curl -X PUT \
  "https://api-us.messaging.acrobits.cz/app-admin-api/MY_CLOUD_ID/ten-dlc-settings?networkId=my-network" \
  -H "x-app-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "brand": "Acme Corp",
        "contactNumber": "+1-555-0100",
        "contactEmail": "support@acme.com",
        "contactOther": null,
        "enabled": true,
        "customWelcomeText": null,
        "customOptOutText": null,
        "customOptInText": null,
        "customHelpText": null
      }'
```

Responses:

- `200 OK` with the updated settings in the response body (see [Settings response structure](#settings-response-structure-used-in-create-get-and-update)).
- `400 Bad Request` if the body is invalid, or if the settings use `PER_NETWORK_ID` and `networkId` is missing from the query.
- `404 Not Found` if no settings exist for the given `cloudId` + `networkId`.

### Delete 10DLC settings

```
DELETE /app-admin-api/{cloudId}/ten-dlc-settings?networkId={networkId}
```

Deletes the settings identified by `cloudId` + `networkId`.

Example request:

```bash
curl -X DELETE \
  "https://api-us.messaging.acrobits.cz/app-admin-api/MY_CLOUD_ID/ten-dlc-settings?networkId=my-network" \
  -H "x-app-api-key: <your-api-key>"
```

Responses:

- `204 No Content` on success.
- `404 Not Found` if no settings exist for the given `cloudId` + `networkId`.

### Settings response structure used in create, get and update

| Field | Type | Description |
| --- | --- | --- |
| `id` | number | Internal identifier of the settings. |
| `createdAt` | string (ISO-8601, UTC) | Creation timestamp. |
| `mapping` | string | `PER_CLOUD_ID` or `PER_NETWORK_ID` — whether the settings apply to the whole application or to a single network. See [Identifying 10DLC settings](#identifying-10dlc-settings-in-requests). |
| `networkId` | string \| null | Network identifier (null for per-cloud-ID settings). |
| `brand` | string \| null | Business or service name shown in the automated welcome and help messages (see [Automated Message Templates](10dlc.md#automated-message-templates)) for the SMS channels of user accounts within the `networkId` (or `cloudId`). |
| `contactNumber` | string \| null | Contact phone number. |
| `contactEmail` | string \| null | Contact email. |
| `contactOther` | string \| null | Other contact information. |
| `enabled` | boolean | Whether the settings are enabled. |
| `appId` | number | Internal application identifier. |
| `customWelcomeText` | string \| null | Custom welcome/opt-in confirmation text. |
| `customOptOutText` | string \| null | Custom opt-out text. |
| `customOptInText` | string \| null | Custom opt-in text. |
| `customHelpText` | string \| null | Custom help text. |