Submit a port-in

curl --request POST \
  --url https://api.spenza.com/api/v3/port-in \
  --header 'Content-Type: application/json' \
  --data '
{
  "portInNumber": "+15555551234",
  "currentCarrierName": "<string>",
  "currentAccountNumber": "<string>",
  "currentAccountPassword": "<string>",
  "currentBillingAddress": {
    "street1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "street2": "<string>"
  },
  "employeeEmail": "jsmith@example.com",
  "employeeName": "<string>",
  "plan": "<string>",
  "Operator": "<string>",
  "network": "<string>",
  "iccid": "8901260853182965429",
  "subscriberName": "<string>",
  "metaData": {}
}
'

import requests

url = "https://api.spenza.com/api/v3/port-in"

payload = {
    "portInNumber": "+15555551234",
    "currentCarrierName": "<string>",
    "currentAccountNumber": "<string>",
    "currentAccountPassword": "<string>",
    "currentBillingAddress": {
        "street1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "street2": "<string>"
    },
    "employeeEmail": "jsmith@example.com",
    "employeeName": "<string>",
    "plan": "<string>",
    "Operator": "<string>",
    "network": "<string>",
    "iccid": "8901260853182965429",
    "subscriberName": "<string>",
    "metaData": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    portInNumber: '+15555551234',
    currentCarrierName: '<string>',
    currentAccountNumber: '<string>',
    currentAccountPassword: '<string>',
    currentBillingAddress: {
      street1: '<string>',
      city: '<string>',
      state: '<string>',
      zip: '<string>',
      street2: '<string>'
    },
    employeeEmail: 'jsmith@example.com',
    employeeName: '<string>',
    plan: '<string>',
    Operator: '<string>',
    network: '<string>',
    iccid: '8901260853182965429',
    subscriberName: '<string>',
    metaData: {}
  })
};

fetch('https://api.spenza.com/api/v3/port-in', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spenza.com/api/v3/port-in",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'portInNumber' => '+15555551234',
    'currentCarrierName' => '<string>',
    'currentAccountNumber' => '<string>',
    'currentAccountPassword' => '<string>',
    'currentBillingAddress' => [
        'street1' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'zip' => '<string>',
        'street2' => '<string>'
    ],
    'employeeEmail' => 'jsmith@example.com',
    'employeeName' => '<string>',
    'plan' => '<string>',
    'Operator' => '<string>',
    'network' => '<string>',
    'iccid' => '8901260853182965429',
    'subscriberName' => '<string>',
    'metaData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spenza.com/api/v3/port-in"

	payload := strings.NewReader("{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spenza.com/api/v3/port-in")
  .header("Content-Type", "application/json")
  .body("{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spenza.com/api/v3/port-in")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "transactionId": "v3_1715567890123_abc123def456",
  "statusEndpoint": "/api/v3/transaction/v3_1715567890123_abc123def456/status",
  "message": "Port-in initiated",
  "timestamp": "2026-07-31T09:00:00.000Z"
}

{
  "success": false,
  "error": "Plan 'AT0001' not found",
  "timestamp": "2026-07-31T09:00:00.000Z"
}

{
  "success": false,
  "error": "Failed to initiate transaction"
}

Numbers & Port-in

Submit a port-in

The only port-in submission endpoint — there is no POST /api/v1.1/port-ins. Move an existing number from another carrier into Spenza. Always asynchronous.

Two contract exceptions worth calling out:

Requires an account role, not just a valid bearer token — Admin, Super Admin, or Standard Admin.
Response is not on the standard envelope. Success is a flat { success, transactionId, statusEndpoint, message, timestamp } — no data wrapper — and statusEndpoint points at the singular legacy path /api/v3/transaction/{id}/status (not the plural /api/v3/transactions/{id} used everywhere else — both resolve, but this is the literal value returned). A synchronous validation error is { success: false, error: "<plain string>", timestamp } — note error is a bare string here, not an {code, message} object.

Identify the target line via plan, or via Operator + network directly. Idempotency is supported via an Idempotency-Key header (handled inline, not the standard interceptor) — a replay returns the same shape with message: "Port-in already initiated (idempotent replay)".

POST

api

port-in

Submit a port-in

curl --request POST \
  --url https://api.spenza.com/api/v3/port-in \
  --header 'Content-Type: application/json' \
  --data '
{
  "portInNumber": "+15555551234",
  "currentCarrierName": "<string>",
  "currentAccountNumber": "<string>",
  "currentAccountPassword": "<string>",
  "currentBillingAddress": {
    "street1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "street2": "<string>"
  },
  "employeeEmail": "jsmith@example.com",
  "employeeName": "<string>",
  "plan": "<string>",
  "Operator": "<string>",
  "network": "<string>",
  "iccid": "8901260853182965429",
  "subscriberName": "<string>",
  "metaData": {}
}
'

import requests

url = "https://api.spenza.com/api/v3/port-in"

payload = {
    "portInNumber": "+15555551234",
    "currentCarrierName": "<string>",
    "currentAccountNumber": "<string>",
    "currentAccountPassword": "<string>",
    "currentBillingAddress": {
        "street1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "street2": "<string>"
    },
    "employeeEmail": "jsmith@example.com",
    "employeeName": "<string>",
    "plan": "<string>",
    "Operator": "<string>",
    "network": "<string>",
    "iccid": "8901260853182965429",
    "subscriberName": "<string>",
    "metaData": {}
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    portInNumber: '+15555551234',
    currentCarrierName: '<string>',
    currentAccountNumber: '<string>',
    currentAccountPassword: '<string>',
    currentBillingAddress: {
      street1: '<string>',
      city: '<string>',
      state: '<string>',
      zip: '<string>',
      street2: '<string>'
    },
    employeeEmail: 'jsmith@example.com',
    employeeName: '<string>',
    plan: '<string>',
    Operator: '<string>',
    network: '<string>',
    iccid: '8901260853182965429',
    subscriberName: '<string>',
    metaData: {}
  })
};

fetch('https://api.spenza.com/api/v3/port-in', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spenza.com/api/v3/port-in",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'portInNumber' => '+15555551234',
    'currentCarrierName' => '<string>',
    'currentAccountNumber' => '<string>',
    'currentAccountPassword' => '<string>',
    'currentBillingAddress' => [
        'street1' => '<string>',
        'city' => '<string>',
        'state' => '<string>',
        'zip' => '<string>',
        'street2' => '<string>'
    ],
    'employeeEmail' => 'jsmith@example.com',
    'employeeName' => '<string>',
    'plan' => '<string>',
    'Operator' => '<string>',
    'network' => '<string>',
    'iccid' => '8901260853182965429',
    'subscriberName' => '<string>',
    'metaData' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spenza.com/api/v3/port-in"

	payload := strings.NewReader("{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spenza.com/api/v3/port-in")
  .header("Content-Type", "application/json")
  .body("{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spenza.com/api/v3/port-in")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"portInNumber\": \"+15555551234\",\n  \"currentCarrierName\": \"<string>\",\n  \"currentAccountNumber\": \"<string>\",\n  \"currentAccountPassword\": \"<string>\",\n  \"currentBillingAddress\": {\n    \"street1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"zip\": \"<string>\",\n    \"street2\": \"<string>\"\n  },\n  \"employeeEmail\": \"jsmith@example.com\",\n  \"employeeName\": \"<string>\",\n  \"plan\": \"<string>\",\n  \"Operator\": \"<string>\",\n  \"network\": \"<string>\",\n  \"iccid\": \"8901260853182965429\",\n  \"subscriberName\": \"<string>\",\n  \"metaData\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "transactionId": "v3_1715567890123_abc123def456",
  "statusEndpoint": "/api/v3/transaction/v3_1715567890123_abc123def456/status",
  "message": "Port-in initiated",
  "timestamp": "2026-07-31T09:00:00.000Z"
}

{
  "success": false,
  "error": "Plan 'AT0001' not found",
  "timestamp": "2026-07-31T09:00:00.000Z"
}

{
  "success": false,
  "error": "Failed to initiate transaction"
}

Headers

Idempotency-Key

string

Any string unique to this logical request. On a retry with the same key and the same request body, the original response is replayed verbatim (with an Idempotency-Replayed: true response header) instead of the action repeating. Reusing the key with a different body or on a different route returns 409 IDEMPOTENCY_KEY_REUSED. A replay attempted while the original call is still in flight returns 409 CONFLICT. Optional — omit it and the endpoint behaves exactly as it would otherwise.

Example:

"a1b2c3d4-idem-key-001"

Body

application/json

portInNumber

string

required

10-15 digits, optional leading +, cannot be all zeros.

Example:

"+15555551234"

currentCarrierName

string

required

currentAccountNumber

string

required

currentAccountPassword

string

required

Losing carrier's account PIN (FCC LNP) — treat like a credential, never log it.

currentBillingAddress

object

required

Show child attributes

employeeEmail

string<email>

required

Auto-creates the user on this account if no match exists.

employeeName

string

required

Used when auto-creating the user.

plan

string

Plan/product name; operator+network derived from it. Required when Operator/network are absent.

Operator

string

Required when plan is absent.

network

string

Required when plan is absent.

iccid

string

19-20 digits.

Example:

"8901260853182965429"

targetPortinClassification

enum<string>

Available options:

mvno,

iot

subscriberName

string

Defaults to employeeName if omitted.

metaData

object

Free-form partner metadata for correlation.

Response

Port-in initiated (note the flat, non-enveloped shape).

Overview

Build

Reference

Help

API Reference

Submit a port-in

Headers

Body

Response