Phone_API

Phone numbers are a custom telephony product. Agents rent numbers by country and capability, then manage balance top-ups, inbound SMS, and missed calls through the same agent API or MCP surface.

Agent_Flow

Example MCP-style transcript. Each next action reuses the identifiers returned by the previous response.

text

1. catalog_search { category: "telephony", q: "phone number", limit: 3 }
2. catalog_checkout_requirements { catalogItemId }
3. quote_create {
     catalogItemId,
     quantity: 1,
     configuration: {
       countryCode: "US",
       numberType: "local",
       capabilities: ["sms", "voice"],
       locality: "new-york",
       initialBalanceUsd: 10
     }
   }
4. purchase_create { quoteId, idempotencyKey }
5. service_get { serviceId }
6. phone_balance_topup { serviceId, amountUsd: 10 }
7. phone_message_list / phone_message_get
8. phone_missed_call_list
9. phone_call_log_get

Step_1_Request_Search

json

{
  "tool": "catalog_search",
  "input": {
    "category": "telephony",
    "q": "phone number",
    "limit": 3
  }
}

Step_1_Response

json

{
  "items": [
    {
      "id": "cat_phone_global_001",
      "sku": "phone-global-rental",
      "name": "Global Phone Numbers",
      "category": "telephony",
      "checkoutKind": "custom"
    }
  ]
}

Step_2_Request_Checkout_Requirements

json

{
  "tool": "catalog_checkout_requirements",
  "input": {
    "catalogItemId": "cat_phone_global_001"
  }
}

Step_2_Response

json

{
  "catalogItemId": "cat_phone_global_001",
  "checkoutKind": "custom",
  "serviceType": "phone_number",
  "requiredFields": [
    "countryCode",
    "numberType",
    "capabilities"
  ],
  "managementCapabilities": [
    "phone:balance:topup",
    "phone:messages:read",
    "phone:missed-calls:read"
  ]
}

Step_3_Request_Quote

json

{
  "tool": "quote_create",
  "input": {
    "catalogItemId": "cat_phone_global_001",
    "quantity": 1,
    "configuration": {
      "countryCode": "US",
      "numberType": "local",
      "capabilities": ["sms", "voice"],
      "locality": "new-york",
      "initialBalanceUsd": 10
    }
  }
}

Step_3_Response

json

{
  "quote": {
    "id": "quote_phone_001",
    "catalogItemId": "cat_phone_global_001",
    "totalPriceMinor": 1250,
    "currency": "usd",
    "displayName": "US Local Number + $10 Balance",
    "quoteDetails": {
      "countryCode": "US",
      "numberType": "local",
      "capabilities": ["sms", "voice"],
      "initialBalanceUsd": 10
    }
  }
}

Step_4_Request_Purchase

json

{
  "tool": "purchase_create",
  "input": {
    "quoteId": "quote_phone_001",
    "idempotencyKey": "phone-rental-us-001"
  }
}

Step_4_Response

json

{
  "purchase": {
    "id": "purchase_phone_001",
    "status": "completed",
    "totalPriceMinor": 1250
  },
  "service": {
    "id": "svc_phone_001",
    "serviceType": "phone_number",
    "displayName": "+1 212 555 0186"
  }
}

Step_5_Request_Service

json

{
  "tool": "service_get",
  "input": {
    "serviceId": "svc_phone_001"
  }
}

Step_5_Response

json

{
  "service": {
    "id": "svc_phone_001",
    "status": "active",
    "serviceType": "phone_number",
    "displayName": "+1 212 555 0186",
    "phone": {
      "e164": "+12125550186",
      "countryCode": "US",
      "numberType": "local",
      "capabilities": ["sms", "voice"],
      "balanceUsd": "10.00"
    }
  }
}

Step_6_Request_Topup

json

{
  "tool": "phone_balance_topup",
  "input": {
    "serviceId": "svc_phone_001",
    "amountUsd": 15
  }
}

Step_6_Response

json

{
  "balance": {
    "serviceId": "svc_phone_001",
    "currency": "usd",
    "previousBalanceUsd": "10.00",
    "newBalanceUsd": "25.00"
  }
}

Step_7_Request_Unread_Messages

json

{
  "tool": "phone_message_list",
  "input": {
    "serviceId": "svc_phone_001",
    "limit": 2,
    "unreadOnly": true
  }
}

Step_7_Response

json

{
  "messages": [
    {
      "id": "msg_001",
      "from": "+14155550123",
      "to": "+12125550186",
      "direction": "inbound",
      "bodyPreview": "Your verification code is 834921",
      "receivedAt": "2026-04-01T10:22:19Z"
    }
  ]
}

Step_7B_Request_Message_Get

json

{
  "tool": "phone_message_get",
  "input": {
    "serviceId": "svc_phone_001",
    "messageId": "msg_001"
  }
}

Step_7B_Response

json

{
  "message": {
    "id": "msg_001",
    "from": "+14155550123",
    "to": "+12125550186",
    "body": "Your verification code is 834921",
    "receivedAt": "2026-04-01T10:22:19Z",
    "status": "received"
  }
}

Step_8_Request_Missed_Calls

json

{
  "tool": "phone_missed_call_list",
  "input": {
    "serviceId": "svc_phone_001",
    "limit": 2
  }
}

Step_8_Response

json

{
  "calls": [
    {
      "id": "call_001",
      "from": "+442030000123",
      "to": "+12125550186",
      "status": "missed",
      "startedAt": "2026-04-01T11:02:09Z",
      "durationSeconds": 0
    }
  ]
}

Capabilities

Country and number-type selection during checkout

Separate telephony balance top-up action after purchase

Inbound SMS inbox read APIs for agents

Missed and unanswered call log retrieval

Reusable for OTP, support queues, and local presence

Management actions: phone_balance_topup, phone_message_list, phone_message_get, phone_missed_call_list, phone_call_log_get

Available_Countries

US • United States

sms + voice • local, mobile, national

CA • Canada

sms + voice • local, mobile

GB • United Kingdom

sms + voice • local, mobile, national

DE • Germany

sms + voice • local, national

FR • France

sms + voice • local, mobile

NL • Netherlands

sms + voice • local, mobile

ES • Spain

sms + voice • local, mobile

AU • Australia

sms + voice • local, mobile, national

NZ • New Zealand

sms + voice • local, mobile

SG • Singapore

sms + voice • local, mobile

JP • Japan

sms + voice • local, mobile

BR • Brazil

sms + voice • local, mobile

REST_Examples

Topup_Balance

typescript

await fetch('https://ag3n7.store/v1/agent/services/<service-id>/phone/topups', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    amountUsd: 15,
  }),
});

Read_Inbox_And_Missed_Calls

typescript

const inbox = await fetch('https://ag3n7.store/v1/agent/services/<service-id>/phone/messages?limit=10&unreadOnly=true', {
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
  },
}).then((res) => res.json());
 
const missed = await fetch('https://ag3n7.store/v1/agent/services/<service-id>/phone/missed-calls?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
  },
}).then((res) => res.json());