DialB Logo
API docs by Redocly

DialB API (v1)

Download OpenAPI specification:Download

Comprehensive API for managing DIDs (phone numbers), groups, spam checks, and user accounts for the DialB service. Provides endpoints for single and bulk spam checks, job management for asynchronous operations, DID and group CRUD operations, API key management, and user account details.

Authentication

User Login

Authenticates a user with email and password, returning a session token (API key).

Request Body schema: application/json
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Account

Get My Account Details

Retrieves detailed information for the authenticated user, including profile, limits, and rate limit usage.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "user@example.com",
  • "role": "client",
  • "is_active": true,
  • "daily_limit": 0,
  • "weekly_limit": 0,
  • "monthly_limit": 0,
  • "can_use_tmobile": true,
  • "can_use_att": true,
  • "can_use_third_party": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "daily_lookups_used": 0,
  • "daily_lookups_remaining": 0,
  • "weekly_lookups_used": 0,
  • "weekly_lookups_remaining": 0,
  • "monthly_lookups_used": 0,
  • "monthly_lookups_remaining": 0
}

Generate API Key

Generates a new API key for the authenticated user.

Authorizations:
BearerAuth
Request Body schema: application/json

Optional description and expiration for the new API key.

description
string or null
expires_at
string or null <date-time>

ISO 8601 timestamp string.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "key_prefix": "string",
  • "description": "string",
  • "type": "string",
  • "is_active": true,
  • "expires_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "apiKey": "string",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

List API Keys

Lists metadata for all API keys belonging to the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Deactivate API Key

Deactivates (soft-deletes) a specific API key.

Authorizations:
BearerAuth
path Parameters
keyId
required
string <uuid>

ID of the API key to deactivate.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

Reactivate API Key

Reactivates a previously deactivated API key.

Authorizations:
BearerAuth
path Parameters
keyId
required
string <uuid>

ID of the API key to reactivate.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

Permanently Delete API Key

Permanently deletes a specific API key. This action is irreversible.

Authorizations:
BearerAuth
path Parameters
keyId
required
string <uuid>

ID of the API key to permanently delete.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

DIDs

Create DID Export Job

Initiates an asynchronous job to export DIDs based on specified filters.

Authorizations:
BearerAuth
Request Body schema: application/json
required
object (DIDExportFilters)
excludedIds
Array of strings or null <uuid>

List of DID IDs to exclude from the export.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "excludedIds": [
    ]
}

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "message": "string",
  • "status": "Pending",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Create DID Import Job (Async)

Initiates an asynchronous job to import DIDs. Accepts either a JSON payload with 'pastedNumbers' or multipart/form-data with a 'file'.

Authorizations:
BearerAuth
Request Body schema:
pastedNumbers
required
string

A string containing numbers, typically newline or comma separated.

targetGroupId
string or null <uuid>

Optional ID of an existing group to import DIDs into.

newGroupName
string or null

Optional name for a new group to be created for these DIDs.

trackSpam
required
boolean

Whether to track spam status for these DIDs.

Responses

Request samples

Content type
{
  • "pastedNumbers": "string",
  • "targetGroupId": "48ef2c38-9f7c-40bd-9b53-7e9ad33e6373",
  • "newGroupName": "string",
  • "trackSpam": true
}

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "message": "string"
}

Import DIDs (Synchronous)

Synchronously imports a list of DIDs into a specified group. Might be deprecated.

Authorizations:
BearerAuth
Request Body schema: application/json
phoneNumbers
required
Array of strings
groupId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "phoneNumbers": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "totalInRequest": 0,
  • "uniqueValidProcessed": 0,
  • "createdCount": 0,
  • "alreadyExistedCount": 0,
  • "ignoredFromRequestCount": 0
}

List DIDs

Lists DIDs for the authenticated user with pagination and filtering.

Authorizations:
BearerAuth
query Parameters
page
integer
Default: 1
pageSize
integer
Default: 10
exportAll
boolean
Default: false
groupId
string <uuid>
searchNumber
string
overallStatus
string (OverallDIDStatus)
Enum: "Clean" "Spam" "Failed"

Overall consolidated spam status for a DID.

sortBy
string
Default: "created_at"
Enum: "phone_number" "group_name" "latest_overall_status" "last_checked_at" "created_at" "updated_at"
sortOrder
string
Default: "desc"
Enum: "asc" "desc"

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Get DIDs Count

Retrieves the total count of DIDs for the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get DIDs Statistics

Retrieves statistics about DIDs, e.g., count of spam DIDs in a period.

Authorizations:
BearerAuth
query Parameters
status
string (OverallDIDStatus)
Enum: "Clean" "Spam" "Failed"

Filter by overall status (Spam, Clean, Failed).

period
string
Default: "all"

Time period for stats (e.g., "7d", "30d", "all").

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Bulk Assign DIDs to Group

Assigns multiple DIDs to a specified group.

Authorizations:
BearerAuth
Request Body schema: application/json
did_ids
required
Array of strings <uuid>
group_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "did_ids": [
    ],
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "updatedCount": 0,
  • "notFoundCount": 0
}

Bulk Delete DIDs

Deletes multiple DIDs.

Authorizations:
BearerAuth
Request Body schema: application/json
did_ids
required
Array of strings <uuid>

Responses

Request samples

Content type
application/json
{
  • "did_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedCount": 0,
  • "notFoundCount": 0
}

Get DID Details

Retrieves details for a specific DID.

Authorizations:
BearerAuth
path Parameters
didId
required
string <uuid>

ID of the DID.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "phone_number": "string",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "group_name": "string",
  • "latest_tmobile_status": "true",
  • "latest_att_status": "true",
  • "latest_third_party_status": "true",
  • "latest_overall_status": "Clean",
  • "last_checked_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Update DID Group

Updates the group assignment for a specific DID.

Authorizations:
BearerAuth
path Parameters
didId
required
string <uuid>

ID of the DID to update.

Request Body schema: application/json
groupId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "phone_number": "string",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "group_name": "string",
  • "latest_tmobile_status": "true",
  • "latest_att_status": "true",
  • "latest_third_party_status": "true",
  • "latest_overall_status": "Clean",
  • "last_checked_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete DID

Deletes a specific DID.

Authorizations:
BearerAuth
path Parameters
didId
required
string <uuid>

ID of the DID to delete.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

Get DID Check History

Retrieves the spam check history for a specific DID, paginated.

Authorizations:
BearerAuth
path Parameters
didId
required
string <uuid>

ID of the DID.

query Parameters
page
integer
Default: 1
pageSize
integer
Default: 10

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Groups

Create Group

Creates a new group for organizing DIDs.

Authorizations:
BearerAuth
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "total_dids": 0,
  • "spam_dids": 0,
  • "clean_dids": 0,
  • "failed_dids": 0
}

List Groups

Lists all groups for the authenticated user with pagination and DID counts.

Authorizations:
BearerAuth
query Parameters
page
integer
Default: 1
pageSize
integer
Default: 10

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Get Groups Count

Retrieves the total count of groups for the authenticated user.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Get Group Details

Retrieves details for a specific group.

Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

ID of the group.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "total_dids": 0,
  • "spam_dids": 0,
  • "clean_dids": 0,
  • "failed_dids": 0
}

Update Group

Updates the name of a specific group.

Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

ID of the group to update.

Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "total_dids": 0,
  • "spam_dids": 0,
  • "clean_dids": 0,
  • "failed_dids": 0
}

Delete Group

Deletes a specific group. If the group contains DIDs, an 'action' query parameter is required:

  • action=delete_dids: Deletes all DIDs in the group, then the group.
  • action=reassign_dids&new_group_id=<uuid>: Reassigns DIDs to new_group_id, then deletes the group. The 'Uncategorized' group cannot be deleted.
Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

ID of the group to delete.

query Parameters
action
string
Enum: "delete_dids" "reassign_dids"

Action to take if the group is not empty ('delete_dids' or 'reassign_dids').

new_group_id
string <uuid>

ID of the group to reassign DIDs to (required if action=reassign_dids).

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

Delete DIDs in Group

Deletes all DIDs within a specific group.

Authorizations:
BearerAuth
path Parameters
groupId
required
string <uuid>

ID of the group from which to delete DIDs.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "deletedCount": 0
}

Spam Checks

Single Phone Number Check

Performs a spam check on a single phone number.

Authorizations:
BearerAuth
Request Body schema: application/json
phoneNumber
required
string

The phone number to check.

groupId
string or null <uuid>

Optional group ID to associate the DID with.

Responses

Request samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55"
}

Response samples

Content type
application/json
{
  • "phoneNumber": "string",
  • "tmobileStatus": "true",
  • "attStatus": "true",
  • "thirdPartyStatus": "true",
  • "overallStatus": "Clean",
  • "usage": {
    }
}

Bulk Phone Number Check

Initiates an asynchronous bulk spam check job for a list of phone numbers or DIDs in a group.

Authorizations:
BearerAuth
Request Body schema: application/json
phoneNumbers
Array of strings

List of phone numbers to check. Max 10,000.

groupId
string or null <uuid>

Optional group ID. If provided and phoneNumbers is empty, all DIDs in this group will be checked.

Responses

Request samples

Content type
application/json
{
  • "phoneNumbers": [
    ],
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55"
}

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "message": "string",
  • "count": 0
}

Create Bulk Check Job with Filters

Initiates an asynchronous bulk spam check job for DIDs matching specified filters.

Authorizations:
BearerAuth
Request Body schema: application/json
object (DIDExportFilters)
excluded_ids
Array of strings or null <uuid>

List of DID IDs to exclude from the filtered check.

Responses

Request samples

Content type
application/json
{
  • "filters": {
    },
  • "excluded_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "jobId": "9d222c6d-893e-4e79-8201-3c9ca16a0f39",
  • "message": "string"
}

Jobs

List Jobs

Lists all jobs for the authenticated user with pagination.

Authorizations:
BearerAuth
query Parameters
page
integer
Default: 1

Page number for pagination.

pageSize
integer
Default: 10

Number of items per page.

Responses

Response samples

Content type
application/json
{
  • "pagination": {
    },
  • "results": [
    ]
}

Get Job Status

Retrieves the status and details of a specific job.

Authorizations:
BearerAuth
path Parameters
jobId
required
string <uuid>

ID of the job to retrieve.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  • "type": "BulkCheck",
  • "status": "Pending",
  • "total_numbers": 0,
  • "processed_numbers": 0,
  • "successfully_checked_numbers": 0,
  • "failed_check_numbers": 0,
  • "spamNumbers": 0,
  • "cleanNumbers": 0,
  • "group_name": "string",
  • "file_path": "string",
  • "file_error": "string",
  • "input_type": "string",
  • "original_file_name": "string",
  • "new_group_name": "string",
  • "track_spam": true,
  • "total_in_request": 0,
  • "unique_valid_processed": 0,
  • "dids_created_count": 0,
  • "dids_updated_count": 0,
  • "dids_ignored_count": 0,
  • "dids_failed_count": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "user_deleted_at": "2019-08-24T14:15:22Z"
}

Get Job Results

Retrieves the results of a completed bulk check job, with pagination or full export.

Authorizations:
BearerAuth
path Parameters
jobId
required
string <uuid>

ID of the job.

query Parameters
page
integer
Default: 1

Page number for paginated results. Not used if exportAll=true.

pageSize
integer
Default: 10

Number of results per page. Not used if exportAll=true.

exportAll
boolean
Default: false

Set to 'true' to export all results.

format
string
Default: "csv"
Enum: "csv" "txt"

Export format ('csv' or 'txt'). Used only if exportAll=true.

Responses

Response samples

Content type
{
  • "pagination": {
    },
  • "results": [
    ]
}

Download Export File

Downloads a file generated by an export job (e.g., ExportDIDs job).

Authorizations:
BearerAuth
path Parameters
jobId
required
string <uuid>

ID of the export job.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}

Hide Job

Soft-deletes a job, marking it as hidden by the user.

Authorizations:
BearerAuth
path Parameters
jobId
required
string <uuid>

ID of the job to hide.

Responses

Response samples

Content type
application/json
{
  • "error": "string",
  • "details": { }
}