# Port Numbers

Transfer your existing phone numbers from other carriers to KrosAI. Keep your established business numbers while gaining access to our AI voice platform.

## Overview

Number porting allows you to move phone numbers you already own to KrosAI without changing the actual number. Your customers and contacts can continue reaching you at the same number.

## Porting Process

Submit Request → Validation → Carrier Coordination → Port Complete → Configure AI (Day 1) (Day 2) (Days 3-10) (Day 11-15) (Ready!)

{% stepper %}
{% step %}

### Submit Port Request

Start a port request from the Dashboard or API:

{% code title="Create port request (curl)" %}

```bash
curl -X POST "https://api.krosai.com/v1/port-requests" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+2348012345678",
    "country": "NG",
    "current_carrier": "mtn",
    "account_number": "ACC123456",
    "authorized_name": "John Smith",
    "authorized_date": "2025-01-15",
    "billing_name": "Acme Corporation",
    "billing_address": "123 Business St, Lagos"
  }'
```

{% endcode %}
{% endstep %}

{% step %}

### Submit Documentation

Upload required documents:

* **Letter of Authorization (LOA)** - Signed authorization to port
* **Recent Bill** - From current carrier (within 90 days)
* **Government ID** - Of authorized signatory
  {% endstep %}

{% step %}

### Carrier Coordination

KrosAI works with carriers to coordinate the transfer:

* We submit the port request to the losing carrier
* Resolve any rejections or issues
* Schedule the port date
  {% endstep %}

{% step %}

### Port Completion

On the scheduled date:

* Number transfers to KrosAI infrastructure
* Inbound calls begin routing to our platform
* You receive confirmation notification
  {% endstep %}

{% step %}

### Configure Routing

Once ported, configure your AI agent:

{% code title="Configure routing (curl)" %}

```bash
curl -X PATCH "https://api.krosai.com/v1/phone-numbers/pn_abc123" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint_id": "ep_your_agent"
  }'
```

{% endcode %}
{% endstep %}
{% endstepper %}

## Required Information

| Field              | Description                  | Example                     |
| ------------------ | ---------------------------- | --------------------------- |
| `phone_number`     | Number to port (E.164)       | `+2348012345678`            |
| `country`          | ISO country code             | `NG`                        |
| `current_carrier`  | Current service provider     | `mtn`, `airtel`, `etisalat` |
| `account_number`   | Account with current carrier | `ACC123456`                 |
| `account_pin`      | Account PIN (if applicable)  | `1234`                      |
| `authorized_name`  | Person authorized to port    | `John Smith`                |
| `authorized_title` | Title of authorized person   | `Director`                  |
| `authorized_date`  | Date of authorization        | `2025-01-15`                |
| `billing_name`     | Name on account              | `Acme Corporation`          |
| `billing_address`  | Service address              | `123 Business St, Lagos`    |

## Letter of Authorization (LOA)

The LOA must include:

{% stepper %}
{% step %}

### Phone numbers being ported

List all telephone numbers to be ported.
{% endstep %}

{% step %}

### Current carrier name

Specify the current service provider.
{% endstep %}

{% step %}

### Account information

Include account name and account number.
{% endstep %}

{% step %}

### Authorization statement

A statement granting KrosAI permission to port the numbers.
{% endstep %}

{% step %}

### Signature of authorized party

Signature from the authorized signatory.
{% endstep %}

{% step %}

### Date of signing

Date when the LOA was signed.
{% endstep %}
{% endstepper %}

### Sample LOA Template

{% code title="LOA Template" %}

```
LETTER OF AUTHORIZATION

Date: [DATE]

I, [AUTHORIZED NAME], hereby authorize KrosAI Limited to port the 
following telephone number(s) from [CURRENT CARRIER] to KrosAI:

Phone Number(s): [PHONE NUMBERS]

Account Name: [ACCOUNT NAME]
Account Number: [ACCOUNT NUMBER]

I am the authorized signatory on this account and confirm that this 
porting request is legitimate.

Signature: ________________________
Name: [AUTHORIZED NAME]
Title: [TITLE]
Date: [DATE]
```

{% endcode %}

## Port Request Status

Track your port request through these stages:

| Status        | Description                        |
| ------------- | ---------------------------------- |
| `pending`     | Request submitted, awaiting review |
| `in_progress` | Submitted to losing carrier        |
| `scheduled`   | Port date confirmed                |
| `completed`   | Port successful, number active     |
| `rejected`    | Port rejected (see reason)         |
| `cancelled`   | Request cancelled                  |

### Check Status

{% code title="Get port request (curl)" %}

```bash
curl -X GET "https://api.krosai.com/v1/port-requests/pr_abc123" \
  -H "x-api-key: kros_live_your_key"
```

{% endcode %}

Response:

{% code title="Example response" %}

```json
{
  "id": "pr_abc123",
  "phone_number": "+2348012345678",
  "status": "in_progress",
  "current_carrier": "mtn",
  "scheduled_port_date": "2025-01-25",
  "created_at": "2025-01-10T10:00:00Z",
  "events": [
    {
      "event_type": "submitted",
      "created_at": "2025-01-10T10:00:00Z"
    },
    {
      "event_type": "carrier_notified",
      "created_at": "2025-01-11T14:30:00Z"
    }
  ]
}
```

{% endcode %}

## Common Rejection Reasons

| Reason                    | Solution                                        |
| ------------------------- | ----------------------------------------------- |
| **Account name mismatch** | Ensure LOA matches exactly with carrier records |
| **Outstanding balance**   | Pay any pending bills with current carrier      |
| **Contract obligation**   | Check if number is under contract term          |
| **PIN incorrect**         | Verify or reset account PIN with carrier        |
| **Address mismatch**      | Update to match carrier's service address       |

## Porting Timeline by Country

| Country      | Typical Duration    | Notes                   |
| ------------ | ------------------- | ----------------------- |
| Nigeria      | 5-10 business days  | Depends on carrier      |
| Ghana        | 5-7 business days   |                         |
| Kenya        | 7-10 business days  |                         |
| South Africa | 10-15 business days | ICASA regulations       |
| UAE          | 7-10 business days  | TRA compliance required |
| Egypt        | 10-15 business days |                         |

## API Reference

### Create Port Request

```
POST /port-requests
```

### Get Port Request

```
GET /port-requests/{id}
```

### List Port Requests

```
GET /port-requests
```

### Cancel Port Request

```
DELETE /port-requests/{id}
```

> Note: Can only cancel requests in `pending` or `in_progress` status.

## Best Practices

### Before Porting

* ✅ Verify you have account access with current carrier
* ✅ Check for contract obligations or early termination fees
* ✅ Ensure no outstanding balance
* ✅ Confirm authorized signatory availability

### During Porting

* ✅ Keep current service active until port completes
* ✅ Monitor port request status
* ✅ Respond promptly to any documentation requests

### After Porting

* ✅ Test inbound calls immediately
* ✅ Configure AI endpoint routing
* ✅ Update any webhooks or integrations
* ✅ Cancel old carrier service (they won't auto-cancel)

## Pricing

| Item             | Cost                      |
| ---------------- | ------------------------- |
| Port Request Fee | $25.00 per number         |
| Monthly Fee      | Same as purchased numbers |
| Per-Minute Rates | Same as purchased numbers |

Port fees are charged upon successful completion only.

## Support

Having issues with your port request?

* **Email:** <porting@krosai.com>
* **Dashboard:** Submit a support ticket
* **Typical Response:** Within 24 hours

## Next Steps

* [View Country Coverage](file:///numbers/countries)
* [Configure Endpoints](file:///voice/endpoints)
* [Set Up Webhooks](file:///webhooks/overview)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/numbers/port-numbers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.