Numbers

Rymi does not sell or purchase phone numbers. Provision numbers in your Plivo, Twilio, Telnyx, or Vonage account, then connect that provider with the Telephony API.

The Numbers API manages numbers already registered or synced into Rymi for agent assignment. It does not search carrier inventory, purchase new numbers, or release numbers from the carrier account.

When you register or attach a number with an agent, Rymi also configures the carrier's inbound voice webhook automatically for Twilio, Plivo, Telnyx, and Vonage. The outcome is returned in a webhook object and mirrored on the number's webhook_status (configured, manual_required, failed, or null). For Vonage, Rymi finds or creates a shared "Rymi Inbound" voice application and links the number's answer URL to it (this needs the signature_secret set at connect time).

Register BYOC Number

POST/v1/numbers

Create a local Rymi registration for a number you already own in your carrier account.

Request Body

Field	Type	Required	Default	Description
number	string	Yes	—	Carrier-owned phone number in E.164 format (e.g., +15551234567)
agent_id	uuid	No	null	Agent UUID to attach immediately upon registration

Example Request

cURL

curl -X POST https://api.rymi.live/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+15551234567",
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Node.js

const result = await rymi.numbers.register("+15551234567", {
  agent_id: "550e8400-e29b-41d4-a716-446655440000",
});

Python

result = rymi.numbers.register(
    "+15551234567",
    agent_id="550e8400-e29b-41d4-a716-446655440000",
)

Response 201

{
  "status": "registered",
  "number": "+15551234567",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook": {
    "status": "configured",
    "provider": "twilio",
    "webhookUrl": "https://gateway.rymi.live/inbound/twilio",
    "verified": true
  }
}

The webhook object is present only when an agent_id is bound (routing needs an agent). status is one of configured, manual_required (copy webhookUrl into your carrier console), failed (see error), or no_carrier. Webhook setup never blocks the registration itself.

If the number is already registered to the same tenant, Rymi returns 200 and updates agent_id when provided. If the number belongs to another tenant, Rymi returns 409.

Errors

Status	Meaning
400	Invalid phone number format
401	Missing or invalid API key
403	Agent not found in your account (the agent_id doesn't belong to your tenant)
409	Number already registered to another tenant
429	Phone-number quota exceeded for your plan (response includes code, limit, used)

---

Attach Number to Agent

POST/v1/numbers/:number/attach

Link a registered BYOC number to a specific agent. When this number receives an inbound call, the specified agent's persona handles it.

Path Parameters

Parameter	Type	Description
number	string	Registered BYOC number in E.164 format

Request Body

Field	Type	Required	Description
agent_id	uuid	Yes	UUID of the agent to attach

Example Request

cURL

curl -X POST https://api.rymi.live/v1/numbers/+15551234567/attach \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Node.js

const result = await rymi.numbers.attach(
  "+15551234567",
  "550e8400-e29b-41d4-a716-446655440000",
);

Python

result = rymi.numbers.attach(
    "+15551234567",
    agent_id="550e8400-e29b-41d4-a716-446655440000",
)

Response 201

{
  "status": "attached",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "+15551234567",
  "webhook": {
    "status": "configured",
    "provider": "twilio",
    "webhookUrl": "https://gateway.rymi.live/inbound/twilio",
    "verified": true
  }
}

The webhook object reports carrier-side auto-provisioning, same shape as Register. To re-run it after fixing carrier state, call Provision Webhook.

Errors

Status	Meaning
400	Invalid phone number format or missing agent_id
401	Missing or invalid API key
403	Agent not found in your account
404	Number not registered for this tenant

---

Provision Carrier Webhook

POST/v1/numbers/:number/webhook

Re-run carrier inbound-webhook auto-configuration for a registered number. Use after fixing carrier credentials or console state (e.g. correcting a Telnyx Connection ID), or to move a manual_required/failed number to configured.

Path Parameters

Parameter	Type	Description
number	string	Registered BYOC number in E.164 format

Example Request

cURL

curl -X POST https://api.rymi.live/v1/numbers/+15551234567/webhook \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const result = await rymi.numbers.provisionWebhook("+15551234567");

Response 200

{
  "number": "+15551234567",
  "webhook": {
    "status": "configured",
    "provider": "twilio",
    "webhookUrl": "https://gateway.rymi.live/inbound/twilio",
    "verified": true
  }
}

Errors

Status	Meaning
400	Invalid phone number format
401	Missing or invalid API key
404	Number not registered for this tenant

---

Detach Number from Agent

POST/v1/numbers/:number/detach

Clears the agent association from a registered number. The number stays registered in Rymi. Inbound calls to it stop routing to an agent.

Path Parameters

Parameter	Type	Description
number	string	Registered BYOC number in E.164 format

Example Request

curl -X POST https://api.rymi.live/v1/numbers/+15551234567/detach \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "status": "detached",
  "number": "+15551234567"
}

Errors

Status	Meaning
400	Invalid phone number format
401	Missing or invalid API key
404	Number not registered for this tenant

---

List Numbers

GET/v1/numbers

Retrieve a paginated list of phone numbers registered for your tenant.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Max records to return (max 500)
offset	integer	0	Records to skip

Example Request

cURL

curl "https://api.rymi.live/v1/numbers?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const { numbers } = await rymi.numbers.list({ limit: 20, offset: 0 });

Python

result = rymi.numbers.list(limit=20, offset=0)

Response 200

{
  "numbers": [
    {
      "id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "number": "+15551234567",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "is_managed": false,
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

Each row is returned as stored, so the response also passes through internal columns such as user_id and tenant_id. is_managed is false for BYOC numbers you register and true for Rymi-managed numbers.

Errors

Status	Meaning
401	Missing or invalid API key

---

Remove Number Registration

DELETE/v1/numbers/:number

Removes the number registration from Rymi. This does not release, cancel, or delete the number in your carrier account.

Path Parameters

Parameter	Type	Description
number	string	Registered BYOC number in E.164 format

Example Request

cURL

curl -X DELETE https://api.rymi.live/v1/numbers/+15551234567 \
  -H "Authorization: Bearer YOUR_API_KEY"

Node.js

const result = await rymi.numbers.remove("+15551234567");

Python

result = rymi.numbers.remove("+15551234567")

Response 200

{
  "status": "removed",
  "number": "+15551234567"
}

This call is idempotent. It returns 200 whether or not a matching registration existed, so removing an already-removed or unknown number still succeeds.

Errors

Status	Meaning
400	Invalid phone number format
401	Missing or invalid API key

---

Not Exposed in Self-Serve

Rymi intentionally does not expose carrier inventory search, number purchase, or region availability endpoints. Use your carrier's account or API for those flows, then register the owned number in Rymi.

This keeps telecom onboarding, number inventory, identity/regulatory documentation, number rental, and taxes with the carrier.