10DLC Application Admin API¶

This page describes the endpoints for managing your 10DLC settings through the Messaging Application Admin API. 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 and Getting access.

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

Base URL¶

See 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¶

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.
`brand`	string	yes		Business or service name shown in the automated welcome and help messages (see 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:

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).
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:

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).
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) 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.

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

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).
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:

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.
`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) 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.