Skip to main content

Assign a DID

DID assignment is handled from your MiniVoice account setup. After a DID is assigned, use the DID read endpoints to verify number, status, provider, application_id, and route_mode.

Endpoint​

GET /v1/dids/:id

Method​

GET

Auth requirement​

Bearer application API key.

Business example: verify that the receptionist DID is active and assigned to the application before publishing it as the public support number.

Request body​

None.

Response body​

{
  "id": "did_123",
  "customer_id": "cust_123",
  "application_id": "app_123",
  "number_e164": "+15551230001",
  "provider": "didww",
  "status": "active",
  "route_mode": "webhook",
  "created_at": "2026-05-29T12:00:00Z",
  "updated_at": "2026-05-29T12:00:00Z"
}

Errors​

401 unauthorized. 404 not_found.

Common Error Example​

{
  "error": {
    "code": "not_found",
    "message": "DID not found"
  }
}

Example curl​

curl -sS https://api.minivoice.eu/v1/dids/did_123 \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Test procedure​

Verify the DID is active and assigned to the expected application before placing inbound test calls.

Integration guidance

Use this page as part of a complete MiniVoice integration, not as an isolated reference. Start by wiring the smallest possible version in a test application, then add business logic after you can reproduce the behaviour reliably. Keep the MiniVoice call ID in your own records, because that ID is the easiest way to connect API responses, webhook events, recordings, AI results, and billing details.

When you build the workflow, separate caller experience from backend processing. The caller should hear short prompts and reach a destination quickly. Longer work, such as updating a CRM or creating a support ticket, should happen after your webhook endpoint has accepted the event. This keeps the voice flow responsive and makes retry handling easier.

For manual testing, use one known DID, one known destination number, and one webhook receiver where you can inspect request headers and bodies. Run the same test at least three times: one normal path, one invalid input path, and one timeout or no-answer path. Save the examples that worked as fixtures for future regression tests.

Integration checklist

Treat a DID as the public entry point for an inbound call flow. Confirm the number is assigned to the intended application or route before you publish it to users, then place a real test call and compare the inbound call webhook with your expected application ID and destination.

When changing routing, test after each change with one known caller number. Keep the previous routing target documented in your own change log so you can restore service quickly if the new answer_url or SIP destination does not behave as expected.

Copy/Paste Examples​

Real Request​

curl -sS https://api.minivoice.eu/v1/dids/by-number/+15551230002 \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response​

{
  "id": "did_123",
  "customer_id": "cust_123",
  "application_id": "app_123",
  "number_e164": "+15551230002",
  "provider": "didww",
  "status": "active",
  "route_mode": "webhook",
  "created_at": "2026-05-29T12:00:00Z",
  "updated_at": "2026-05-29T12:00:00Z"
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Check a DID before running inbound receptionist, IVR, or call-forwarding tests.

Common Failure Case​

{
  "error": {
    "code": "not_found",
    "message": "DID not found"
  }
}

Use the error code for branching and log the full response body while testing.