Numbers

Rymi does not sell or purchase phone numbers. Provision numbers in your Plivo, Twilio, 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.

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 -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"
  }'

Response 201

{
  "status": "registered",
  "number": "+15551234567",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000"
}

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
409	Number already registered to another tenant

---

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 -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"
  }'

Response 201

{
  "status": "attached",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "+15551234567"
}

Errors

Status	Meaning
400	Missing agent_id
401	Missing or invalid API key
404	Number not registered for this tenant, or agent not found

---

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 200)
offset	integer	0	Records to skip

Example Request

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

Response 200

{
  "numbers": [
    {
      "number": "+15551234567",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

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 -X DELETE https://api.rymi.live/v1/numbers/+15551234567 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

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

Errors

Status	Meaning
401	Missing or invalid API key
404	Number not registered for this tenant

---

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.