Numbers

Rymi abstracts phone number management through the Plivo SDK. Search, purchase, and attach numbers to agents without ever touching the Plivo dashboard.

Search Numbers

Find available phone numbers in a specific country.

POST /numbers/search

Field	Type	Required	Description
iso	string	✅	Two-letter ISO country code (e.g. US, IN, GB)

curl -X POST https://api.rymi.ai/v1/numbers/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "iso": "US" }'

Response 200

{
  "numbers": [
    { "number": "15551234567", "region": "US", "price": "1.00" },
    { "number": "15559876543", "region": "US", "price": "1.00" }
  ]
}

Buy Number

Purchase a phone number via the Rymi API. Behind the scenes, the API uses your supplied PLIVO_AUTH_ID and PLIVO_AUTH_TOKEN to execute a real phone number purchase. Rymi automatically configures the Plivo answer_url webhook to route initial calls to your Gateway (wss://${GATEWAY_HOST}/ws/plivo).

POST /numbers/buy

Field	Type	Required	Description
number	string	✅	Phone number to purchase (E.164 format)

Response 201

{
  "status": "success",
  "number": "15551234567",
  "message": "Number successfully leased and wired to Rymi Voice Gateway"
}

Attach Number to Agent

Link a purchased number to a specific agent. When this number receives a call, the specified agent's persona will handle it.

POST /numbers/:number/attach

Field	Type	Required	Description
agent_id	string	✅	UUID of the agent to attach

Response 201

{ "status": "attached", "agent_id": "550e8400-...", "number": "15551234567" }

List Numbers

GET /numbers

Response 200

{
  "numbers": [
    { "number": "15551234567", "agent_id": "550e8400-...", "created_at": "2026-03-01T10:00:00Z" }
  ]
}

Release Number

DELETE /numbers/:number

Response 200

{ "status": "released", "number": "15551234567" }