KKeepMyNumber
Get started

Getting started

Port your first number in five steps. Everything on this platform is API-first: anything you can do, you can do with an HTTP call and your API key.

1. Get your API key

Your account and first API key are issued by the platform team. The key looks like pk_live_… and is shown once — store it in a secret manager. Pass it on every request:

curl https://api.example.com/v2/account \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

You can create additional keys (e.g. one per environment) with POST /v2/api_keys and revoke them with DELETE /v2/api_keys/{id}.

2. Register a webhook URL

Porting is asynchronous — orders progress over hours or days. Register a URL so we can push you every status change instead of you polling:

curl -X POST https://api.example.com/v2/webhook_endpoints \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/hooks/porting"}'

The response contains a secret (shown once). Use it to verify the Porting-Signature header on every delivery — see the Webhooks guide.

3. Check portability

Always check before ordering. The response tells you, per number: whether it can be ported, its country and type, the current carrier, and which provider will handle it.

curl -X POST https://api.example.com/v2/portability_checks \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_numbers": ["+14155552671", "+447912345678"]}'

Numbers must be in E.164 format (+ followed by country code and number).

4. Create and submit the order

curl -X POST https://api.example.com/v2/porting_orders \
  -H "Authorization: Bearer pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-port" \
  -d '{
    "phone_numbers": ["+447912345678"],
    "end_user": {
      "entity_name": "Acme Ltd",
      "account_number": "A-1042",
      "location": {"street_address": "1 High Street", "locality": "London",
                   "postal_code": "SW1A 1AA", "country_code": "GB"}
    }
  }'

The response is an array of orders — one request can split into several (see Port-in orders). Each order lists its requirements: fulfill them (upload documents, set text values), then:

curl -X POST https://api.example.com/v2/porting_orders/{order_id}/submit \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

5. Watch it complete

From submission on, we push webhooks: porting_order.status_changed at every step, and number.activated when a number goes live. Your numbers then appear in the registry:

curl https://api.example.com/v2/numbers -H "Authorization: Bearer pk_live_YOUR_KEY"

What next