DialRingo API v1

Overview

The v1 API is read-only: your account profile, your phone numbers, and your call history. All endpoints live under https://app.dialringo.com/api/v1, return JSON, and are scoped to the account that owns the API key. Write operations (such as sending SMS) will arrive in a later version behind their own scopes.

Create an API key

In the dashboard, open Developer in the sidebar (app.dialringo.com/dashboard/developer — owners and admins only). Name the key, pick its scopes, and select Create key. The full secret — it starts with dr_live_ — is shown exactly once, at creation. Copy it immediately; afterwards only the key's prefix is visible, and we store only a SHA-256 hash of the secret. Keys can be revoked from the same page at any time.

Authentication

Send the key as a bearer token on every request:

curl https://app.dialringo.com/api/v1/account \
  -H "Authorization: Bearer dr_live_..."

Requests without a key get 401 {"error": "missing_api_key"}; unknown or revoked keys get 401 {"error": "invalid_api_key"}.

Scopes

Each key carries the scopes you chose at creation (the default is account:read + numbers:read). Calling an endpoint without its scope returns 403 {"error": "insufficient_scope", "required": "<scope>"}.

GET/api/v1/account

Your account profile. Requires account:read.

curl https://app.dialringo.com/api/v1/account \
  -H "Authorization: Bearer dr_live_..."

{
  "data": {
    "id": "0b0f0f5e-8f5f-4a2e-9df3-1c7a4a3f2b10",
    "name": "Riverside Dental",
    "customer_ref": "DRC-000042",
    "billing_status": "subscribed"
  }
}

customer_ref is your human-readable customer number (DRC-…). billing_status reflects the billing state, for example subscribed, no_payment_method, or past_due.

GET/api/v1/numbers

All phone numbers on the account, newest first. Requires numbers:read.

curl https://app.dialringo.com/api/v1/numbers \
  -H "Authorization: Bearer dr_live_..."

{
  "data": [
    {
      "id": "7c9a1d34-2b8e-4f10-a5cd-90e3b2f4a611",
      "phone_number": "+15025550114",
      "status": "active",
      "type": "local",
      "sms_enabled": true,
      "friendly_name": "Main line",
      "created_at": "2026-06-18T14:03:22.51427+00:00"
    }
  ]
}

status is active, porting, or released. type is local or toll_free.

GET/api/v1/cdrs

Call history across all of the account's numbers, newest first. Requires cdrs:read.

curl "https://app.dialringo.com/api/v1/cdrs?limit=2" \
  -H "Authorization: Bearer dr_live_..."

{
  "data": [
    {
      "id": "e2f6c3a1-5d47-49b2-8c15-3fb9d0a7e422",
      "direction": "inbound",
      "from_number": "+15025550114",
      "to_number": "+15025550190",
      "disposition": "voicemail",
      "duration_seconds": 42,
      "started_at": "2026-07-11T18:22:05.113+00:00"
    },
    {
      "id": "a91b7d02-64c8-4e3f-b0aa-57c21e8f9d33",
      "direction": "outbound",
      "from_number": "+15025550190",
      "to_number": "+15025550171",
      "disposition": null,
      "duration_seconds": 187,
      "started_at": "2026-07-11T17:40:11.902+00:00"
    }
  ]
}

direction is inbound or outbound. disposition is the post-call tag set by the agent (for example voicemail, no_answer, follow_up) or null when none was recorded.

Errors

Errors are JSON with a single error field:

Good citizenship

• Treat keys like passwords: server-side only, never in client code or repos.
• Create one key per integration so you can revoke them independently.
• The dashboard shows each key's last-used time, so a leaked or stale key is easy to spot and revoke.

Questions or a use case v1 doesn't cover? Email support@dialringo.com.