Skip to main content

​
Overview

Phone numbers are the bridge between your AI agents and real phone calls. In Callin.io, you’ll manage this in two places:
  • Numbers: Buy numbers through Callin.io, import from providers, or verify a personal number.
  • BYOC (SIP Trunk): Bring your own carrier by connecting Telnyx or any SIP provider.
Use these shortcuts to jump straight into the app:
If you’re getting started quickly, buy a US/Canada number (instant). If you need an international number, be ready to submit documents (country rules vary).

​
Numbers

The Numbers page shows every number connected to your workspace (purchased, imported, personal, Telnyx, or BYOC). From here, you can add new numbers and confirm each number’s status.
Numbers page with the Numbers and Number Requests tabs, the filters by type, the list of numbers, and the + Add Number menu open with Purchase Number, Import from Twilio, Add Personal Number, and Add Telnyx Number.

Screenshot: The Numbers page where you can filter by type and click + Add Number to purchase or import numbers.

​
What you can do in Numbers

The page has two tabs:
  • Numbers: every number in your workspace, with its Type and Status (for example, when it was added and when it renews).
  • Number Requests: your purchase requests for countries outside the US and Canada. See Track your requests below.
When you click + Add Number, you’ll see these options:
  • Purchase Number (buy through Callin.io)
  • Import from Twilio
  • Add Personal Number
  • Add Telnyx Number (after Telnyx is connected)
Use the filters All, Purchased, Twilio, Personal, Telnyx, and BYOC (SIP Trunk), or the Search numbers… box, to quickly find what you’re looking for.

​
Option A: Purchase a number through Callin.io

Buying numbers through Callin.io is the simplest way to get started.

​
US & Canada: instant purchase

For United States and Canada, the purchase flow is instant:

Video: + Add Number → Purchase Number → Search Numbers → select a number.

1
Go to Open Numbers.
2
Click + Add Number → Purchase Number.
3
Choose the Country. You can search the list by name, ISO code, or dialing code.
4
Choose a type:
  • Local: standard local area code.
  • Toll-Free: prefixes such as 800 or 888.
5
(Optional) Use Search by Area Code (example: 415).
6
Click Search Numbers.
7
Select a number from the list. Each one shows its state or province (for example, NV).
8
Click Purchase Selected Number.
After purchase, the number should appear in your list. If you see a warning like “this number is not assigned to any agent,” you still need to assign it to an agent before using it.

​
Other countries: request + documentation

Purchase a New Number window for Spain with the Request Type options New number and Porting, the list of available numbers, the Document Requirements note, and the Start request button.

Screenshot: for countries outside the US and Canada, you choose the request type and a number, then click Start request to load the country-specific documents.

For non-US/Canada countries, purchasing is a request-based flow rather than an instant checkout:
1
Click + Add Number → Purchase Number and choose the Country.
2
Choose the Request Type:
  • New number: get a new number.
  • Porting: keep your existing number (see below).
3
Pick one of the available Numbers. Each one shows the carrier that provides it (for example, telnyx). Depending on the country, you may also choose the number type (for example Local or Mobile).
4
Click Start request. The platform then loads the country-specific information and Document Requirements.
5
Complete the required fields, upload documents, and save each item.
6
Submit the request and pay any required fees. An operator then reviews the request.
You can follow every request in the Number Requests tab.
Porting an existing number
Porting lets you bring a number you already own with another provider, so your customers keep calling the same number.
1
In Purchase a New Number, choose the Country and select Porting as the Request Type.
2
Enter your number in Porting Number and click Check Portability.
3
If the number can be ported, click Start request and complete the Document Requirements, as with a new number.
Porting usually takes longer than buying a new number, because your current provider must release it. Don’t cancel your current line until the number shows up in your Numbers list.
This part of the process is important because the requirements are not always the same. They can change depending on the country, the number type, and whether the request is being made by an individual, a sole proprietorship, or a company.
How the documentation step works
After you click Start request, the form may show a combination of:
  • Text fields you must complete manually
  • Upload fields for supporting documents
  • A Save button for each individual requirement
  • A Pending status until that specific item is correctly saved or uploaded
This means the request is usually completed piece by piece, not all at once. If a field or upload still shows Pending, that requirement is normally not complete yet. In many request-based countries, the form can ask for details such as:
  • Identity document type
  • Identity document number
  • Date of birth
  • Place of birth
  • Identity document issuer
  • Identity document expiration date
  • Local address in the same country
  • Personal Tax Code
  • VAT number
  • Company Tax Code
  • IT Customer Type
  • Proof of Address
  • Passport/ID copy
  • Company Registration certificate
Some labels may also clarify who must provide each item, for example:
  • For legal entities only
  • For legal entities and sole proprietorships only
  • For natural persons and sole proprietorships only
So, even if two customers request numbers in the same country, the required documentation may differ depending on the business type and the exact number category.
In the request form, some fields have their own Save button. Entering a value is not always enough by itself. The item may continue to show Pending until you click Save successfully.
Common document requirements (examples)
Exact requirements depend on the country and number type, but you may be asked for items like:
Proof of address: what usually causes problems
The proof of address document is one of the most common reasons a request is delayed. In many countries, the uploaded proof of address must meet all of these conditions:
  • It must clearly show the same name used in the request, or the company name if the request is for a business
  • It must clearly show the same address entered in the form
  • It must be recent
  • It must be complete and readable
  • It must not be cropped in a way that hides important details
A very important rule is that the bill or address document often must be no more than 3 months old at the time of submission. That usually means you should upload a recent document such as:
  • A utility bill dated within the last 3 months
  • A bank statement dated within the last 3 months
  • An official government or tax letter dated within the last 3 months
Older documents may be rejected even if the address itself is correct.
When you upload a bill or bank statement as proof of address, make sure it is less than 3 months old. If the document is older, the request may remain pending or be rejected during review.
How to prepare documents before uploading
To avoid delays, check each document before you upload it. A good document should be:
  • Clear and readable
  • Complete, not cut off at the edges
  • Consistent with the data entered in the form
  • Current, especially for address documents
  • Relevant to the requester type, whether individual or company
For example, if the request is for a company, the reviewer may expect the company name, company number, tax details, and registration documents to match each other. If the request is for an individual, the reviewer may check that the personal name, ID document, and proof of address all match. Common issues that can slow approval include:
  • The address in the form does not match the uploaded document
  • The uploaded bill is older than 3 months
  • The passport or ID copy is blurry
  • A company request is submitted with personal documents only
  • A field is filled in, but the user did not click Save
  • A document was uploaded, but its status still shows Pending
Common mistake: Uploading the correct file is not always enough. After each upload or text entry, check that the requirement no longer shows Pending.
Fees + review
Some countries show a fee payment step after the documentation is completed. This may include:
  • A one-time activation fee
  • The monthly recurring cost for the number
The request generally moves forward only after the required documents are uploaded and the payment step is completed. After you submit and pay:
  • You’ll receive a Request ID
  • The request is reviewed by an operator
  • Once approved, the number appears in your Numbers list
The review is manual in many cases, which is why approval is not always immediate.
Approval timing can vary by country, provider rules, and document quality. If you need the number for an upcoming launch or campaign, submit the request as early as possible and use recent, clearly readable documents.

​
Track your requests (Number Requests)

The Number Requests tab lists your purchase and porting requests for countries outside the US and Canada.
Number Requests tab with the Status, Flow, and Payment Status filters, the Refresh button, and one card per request showing the country, status, number type, flow, chosen number, date, and payment status.

Screenshot: each card is one request. Use the filters to find requests that need your attention.

Each card shows the country, the request status, the Number Type, the Flow, the Chosen Number, the date, and the payment status. Use the filters to narrow the list: Click Refresh to see the latest status.
Check this tab regularly while a request is open. A request in Needs Info is waiting for you to fix or add something, and Payment Due means it won’t move forward until you pay.

​
Option B: Import numbers from Twilio

If you already own numbers in Twilio, you can import them into Callin.io:
1
Go to Open Numbers.
2
Click + Add Number → Import from Twilio.
3
Enter your Twilio Account SID and Twilio Auth Token.
4
Click Search Twilio Numbers and select the numbers to import.
5
Assign imported numbers to an AI agent when you’re ready to use them.
Common mistake: Copying the wrong Twilio credentials (for example, using a test credential instead of live). If no numbers appear, re-check your Twilio project and permissions.

​
Option C: Add a Personal Number (outbound-only)

A Personal Number is useful when you want to place outbound calls from your own phone number—but it cannot receive inbound calls inside Callin.io.
Add Personal Number modal showing country selector, phone input, an invalid number message, and the verification process steps

Screenshot: The Add Personal Number modal with phone input and the verification process (you receive a verification call and enter the code).

​
Verify your personal number

1
Go to Open Numbers.
2
Click + Add Number → Add Personal Number.
3
Select your country code and enter your phone number.
4
Click Verify Number.
5
You’ll receive a verification call from Twilio.
6
Enter the verification code when prompted.
7
After verification, the number is added to your account.
Personal numbers are outbound-only. If you need inbound calls, use a purchased/imported number or BYOC.

​
Option D: Add/Import Telnyx numbers

If your Telnyx account is connected (via BYOC), you can import active Telnyx numbers into Callin.io:
1
Go to Open Numbers.
2
Click + Add Number → Add Telnyx Number.
3
Use Search numbers… to find them, and check the Pick box of each number you want. Select visible picks all the numbers in the list.
4
Click Import, then assign them to agents as needed.
If you haven’t connected Telnyx yet, the window shows an error about the missing Telnyx API key and no numbers. Connect Telnyx first in BYOC (SIP Trunk).

​
Manage your numbers

In the Numbers list, click the ⋮ menu of a number to manage it:
  • Edit Label: give the number a recognizable name, for example the client or the campaign it’s for.
  • Cancel Subscription (purchased numbers): stop renewing a number you bought through Callin.io.
  • Remove (personal numbers): delete a personal number from your account.
Before you cancel or remove a number, assign another number to the agents that use it, so they can keep making and receiving calls.

​
Assign numbers to agents (so they can be used)

Buying or importing a number is only step one: your agent still needs to use it. If the Numbers list shows This number is not assigned to any agent, assign it before going live:
1
Go to AI Agents.
2
Click the ⋮ menu of the agent and select Assign Number.
3
In the Assign Number to window, find the number (you can search by number, label, or carrier) and click Assign.
Assign Number window for an agent, listing the numbers with their status (assigned to another agent or not assigned), carrier, and an Assign button, plus the Purchase new numbers link.

Screenshot: the Assign Number window shows which numbers are free and which are already in use by another agent.

The Status column tells you whether each number is Not assigned or already Assigned to another agent. If you don’t have a suitable number, click Purchase new numbers.
Common mistake: Assigning a number that another agent is using. As the window warns, assigning it here will detach it from the other agent, and that agent stops using the number.
Keep one “test” number separate from production while you’re iterating on prompts and call flows.

​
BYOC (SIP Trunk)

BYOC means Bring Your Own Carrier. Instead of buying numbers through Callin.io, you connect your own telephony provider using a SIP trunk. Typical reasons to use BYOC:
  • You already have a carrier contract (enterprise telephony)
  • You need custom routing, SBC control, or compliance constraints
  • You want to avoid Callin-managed telephony rules by using your own provider
Go here to set it up: Open BYOC
BYOC page on the Telnyx tab, with the Telnyx API Key field, the Start button, and the setup steps: save the key, fetch numbers, store them, provision the SIP trunk, and create phone numbers.

Screenshot: BYOC setup where you can connect Telnyx and synchronize numbers into Callin.io.

​
What is a SIP Trunk (simple explanation)

A SIP trunk is a connection between a phone carrier and your calling system. Think of it like a “phone line over the internet” that can handle inbound/outbound calls—often used by businesses.

​
Option 1: Connect Telnyx

If you use Telnyx, Callin.io can guide the setup with an API key:
1
Go to Open BYOC.
2
Select the Telnyx tab.
3
Paste your Telnyx API Key.
4
Click Start.
During setup, you’ll typically see steps like:
  • Saving the Telnyx API key
  • Fetching active Telnyx numbers (DIDs)
  • Storing numbers in your Callin.io account
  • Provisioning the SIP trunk (inbound + outbound)
  • Creating provider phone numbers
Once it completes, your Telnyx numbers should appear under Numbers.
If your Telnyx key doesn’t have permission to read numbers/DIDs, Callin.io won’t be able to fetch them.

​
Option 2: Connect another SIP provider (Generic SIP Trunk)

If your provider is not Telnyx, use the Other SIP Provider tab (Generic SIP Trunk / PBX Extension (Any Provider)). It works with a SIP trunk number (DID) and also with an extension of your PBX (your company’s phone system). You’ll configure three tabs: Basic, Inbound, and Outbound.
Other SIP Provider tab in BYOC, with the Basic, Inbound, and Outbound tabs, the Label and Phone Number / Extension fields, the Supports inbound and Supports outbound boxes, and the Save & Import and Reset buttons.

Screenshot: the Generic SIP Trunk / PBX Extension form. Fill in Basic, Inbound, and Outbound, then click Save & Import.

​
Basic

  • Label: A friendly name (example: “HQ SIP Trunk”)
  • Phone Number / Extension (E.164 or extension): the full international number (example: +15551234567) or the PBX extension (example: 101)
  • Supports inbound and Supports outbound: check the directions this number will handle

​
Inbound

Inbound calls go from the carrier to your system.
  • Inbound SBC / FQDN: Your SIP address (example: sip.example.com:5061)
  • Transport: TLS, TCP, or UDP
  • Media encryption: Allowed, Required, or Disabled
Inbound often does not require credentials. Many carriers authenticate inbound calls by IP allowlists or trunk configuration.

​
Outbound

Outbound calls go from Callin.io to your carrier.
  • Outbound SBC / FQDN: Your provider’s SIP server
  • Transport and Media encryption (same options as Inbound)
  • Username and Password: Your SIP credentials
  • Allowed countries (outbound): Worldwide or a Custom list
When finished, click Save & Import. To start over, click Reset. After saving, Callin.io checks that the number can be used for calling. If your SIP settings need attention, you’ll see guidance on this page. The number may still appear in your Numbers list while you fix the configuration.
Common mistake: Using the wrong SBC/FQDN or credentials. If outbound calls fail, re-check your SIP username/password and whether your provider requires a specific port or transport.

​
Minutes and billing (what to expect)

Billing can have two parts: Callin usage and telephony carrier charges. What you see depends on how you connect numbers.

​
Callin compute minutes

Compute minutes represent the time your AI agent is active (listening, processing, responding). This is the core usage metric for AI calling.

​
Callin-managed telephony: important billing notice (first-minute billing)

When you place outbound calls using Callin-managed telephony (numbers purchased through Callin.io and routed through Callin’s carrier), the first-minute billing rule applies:
  • Minimum charge is 1 minute
  • Calls of 60 seconds or more are billed for their actual duration
  • This rule does not apply to:
    • Inbound calls
    • Browser test calls
    • Imported own numbering (Telnyx or Twilio imports)
    • External SIP trunk (BYOC)

​
Personal number billing reminder

Personal numbers are outbound-only, and calls made using a personal number can still fall under Callin-managed telephony rules depending on how your account routes calls.

​
Troubleshooting

​
“I can’t make calls”

  • Check that you have at least one active number
  • Make sure the number is assigned to an agent
  • If using BYOC, confirm your SIP trunk settings are correct (SBC/FQDN, transport, credentials)

​
“My agent doesn’t answer incoming calls”

  • Check that the number is assigned to the agent: go to AI Agents, open the agent’s ⋮ menu and select Assign Number (see Assign numbers to agents)
  • Check Call Direction in the agent’s Agent tab: it must be Inbound or Both. New agents start as Outbound, and an outbound agent doesn’t answer incoming calls. Ultra-low latency (Enhanced) agents don’t have Call Direction: they show as Inbound & Outbound in the agents list, so you only need to assign the number
  • In an Ultra-low latency agent, you can also set an Inbound fallback number in the Advanced tab. If the agent can’t answer, the call is forwarded to that number. See Ultra-low latency agents
  • You don’t need transfer rules for the agent to answer

​
“My personal number isn’t receiving inbound calls”

  • That’s expected: Personal Numbers are outbound-only
  • Use a purchased/imported number or BYOC for inbound calling

​
“Can my company name appear on outbound calls (CNAM)?”

  • The caller name (CNAM) is registered with the carrier of the number, not in Callin
  • If you use a number imported from Twilio, set the caller name in your Twilio account. It then applies to the calls your agents make from Callin
  • For other numbers, contact support@callin.io

​
“My imported numbers don’t show up”

  • Re-check credentials (Twilio SID/Auth Token, Telnyx API Key)
  • Confirm the numbers are active in the provider account
  • Try again and verify you’re using the correct project/sub-account in the provider

​
Final note

If you want the fastest setup, start with a US/Canada number purchased in Callin.io. If you need advanced routing or already have a carrier, connect BYOC. Once your number is added and assigned, your AI agents can place and receive real phone calls at scale.