# Step 1 — pre-import check (numbers:read): one live carrier call.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155551234", "currentCarrier": "Acme Telecom" }'
# Gate on: eligible === true

# Step 2 — create the port (numbers:write): draft: true checkpoints the row
# locally (staging: "draft") and dispatches nothing until the LOA is signed.
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "country": "US",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe",
    "serviceAddress": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    },
    "draft": true
  }'
# Response: { "data": { "id": "port_draft456", "staging": "draft", ... } } — keep the id

# Step 3 — FOC timeline read (numbers:read): a pure read on the stored row,
# no carrier call; echoes focDate the moment the carrier assigns one.
curl "https://api.orbit.devotel.io/api/v1/numbers/porting/port_draft456/timeline" \
  -H "X-API-Key: dv_live_sk_..."

# Step 4 — webhook receiver: one endpoint for every porting event.
curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": [
      "number.ported",
      "porting.request.loa_signed",
      "porting.request.supplement_submitted",
      "porting.request.manual_review_required",
      "porting.request.cancelled"
    ]
  }'

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

// Step 1 — pre-import check: gate on eligible before any create
const check = await orbit.request("POST", "/numbers/porting/check", {
  phoneNumber: "+14155551234",
  currentCarrier: "Acme Telecom",
});
if (check.data.eligible !== true) {
  throw new Error(`Not portable: ${check.data.reasons.join(", ")}`);
}

// Step 2 — create the port: draft checkpoint while the LOA is outstanding
const port = await orbit.request("POST", "/numbers/porting", {
  numbers: ["+14155551234"],
  currentCarrier: "Acme Telecom",
  country: "US",
  accountNumber: "998877",
  authorizedSigner: "Jane Doe",
  serviceAddress: {
    line1: "1 Market St",
    city: "San Francisco",
    state: "CA",
    postalCode: "94105",
    countryCode: "US",
  },
  draft: true,
});
const portId = port.data.id;

// Step 3 — FOC timeline read: a stored-row read; safe to poll, no carrier call
const timeline = await orbit.request("GET", `/numbers/porting/${portId}/timeline`, undefined);
// timeline.data.focDate is set the moment the carrier assigns the cutover date

// Step 4 — webhook receiver: subscribe once, then react to events instead of polling
await orbit.request("POST", "/webhooks", {
  url: "https://yourapp.com/webhooks/orbit",
  events: [
    "number.ported",
    "porting.request.loa_signed",
    "porting.request.supplement_submitted",
    "porting.request.manual_review_required",
    "porting.request.cancelled",
  ],
});

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

# Step 1 — pre-import check: gate on eligible before any create
check = client.request("POST", "/numbers/porting/check", json_body={
    "phoneNumber": "+14155551234",
    "currentCarrier": "Acme Telecom",
})
if check["data"]["eligible"] is not True:
    raise SystemExit(f"Not portable: {', '.join(check['data']['reasons'])}")

# Step 2 — create the port: draft checkpoint while the LOA is outstanding
port = client.request("POST", "/numbers/porting", json_body={
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "country": "US",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe",
    "serviceAddress": {
        "line1": "1 Market St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "countryCode": "US",
    },
    "draft": True,
})
port_id = port["data"]["id"]

# Step 3 — FOC timeline read: a stored-row read; safe to poll, no carrier call
timeline = client.request("GET", f"/numbers/porting/{port_id}/timeline")
# timeline["data"]["focDate"] is set the moment the carrier assigns the cutover date

# Step 4 — webhook receiver: subscribe once, then react to events instead of polling
client.request("POST", "/webhooks", json_body={
    "url": "https://yourapp.com/webhooks/orbit",
    "events": [
        "number.ported",
        "porting.request.loa_signed",
        "porting.request.supplement_submitted",
        "porting.request.manual_review_required",
        "porting.request.cancelled",
    ],
})

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"strings"
)

// The four-call loop in Go stdlib. Each step is one request; print the body
// and keep data.id from step 2 for the later LOA calls.

func postJSON(key, path, body string) string {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1"+path, strings.NewReader(body))
	req.Header.Set("X-API-Key", key)
	req.Header.Set("Content-Type", "application/json")
	return do(req)
}

func get(key, path string) string {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1"+path, nil)
	req.Header.Set("X-API-Key", key)
	return do(req)
}

func do(req *http.Request) string {
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	return string(out)
}

func main() {
	key := os.Getenv("ORBIT_API_KEY")

	// Step 1 — pre-import check: gate on "eligible": true before any create.
	fmt.Println(postJSON(key, "/numbers/porting/check",
		`{"phoneNumber": "+14155551234", "currentCarrier": "Acme Telecom"}`))

	// Step 2 — create the port as a draft; read "id" from the printed body.
	fmt.Println(postJSON(key, "/numbers/porting", `{
	  "numbers": ["+14155551234"], "currentCarrier": "Acme Telecom", "country": "US",
	  "accountNumber": "998877", "authorizedSigner": "Jane Doe",
	  "serviceAddress": {"line1": "1 Market St", "city": "San Francisco", "state": "CA",
	    "postalCode": "94105", "countryCode": "US"},
	  "draft": true
	}`))

	// Step 3 — FOC timeline read; safe to poll, no carrier call.
	fmt.Println(get(key, "/numbers/porting/port_draft456/timeline"))

	// Step 4 — webhook receiver: subscribe once, react to events instead of polling.
	fmt.Println(postJSON(key, "/webhooks", `{
	  "url": "https://yourapp.com/webhooks/orbit",
	  "events": ["number.ported", "porting.request.loa_signed",
	    "porting.request.supplement_submitted", "porting.request.manual_review_required",
	    "porting.request.cancelled"]
	}`))

	// Multipart upload (the bulk-csv and LOA steps below) with the stdlib:
	var buf bytes.Buffer
	w := multipart.NewWriter(&buf)
	f, _ := os.Open("port-in-batch.csv")
	part, _ := w.CreateFormFile("file", "port-in-batch.csv")
	io.Copy(part, f)
	w.Close()
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv", &buf)
	req.Header.Set("X-API-Key", key)
	req.Header.Set("Content-Type", w.FormDataContentType())
	fmt.Println(do(req))
}

require "net/http"
require "json"
require "uri"

KEY = ENV.fetch("ORBIT_API_KEY")
BASE = URI("https://api.orbit.devotel.io/api/v1")

def call(method, path, body = nil, form = nil)
  uri = BASE.dup
  uri.path += path
  req = method == :get ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
  req["X-API-Key"] = KEY
  if form
    req.set_form([["file", File.open(form), filename: File.basename(form)]], "multipart/form-data")
  else
    req["Content-Type"] = "application/json"
    req.body = body && JSON.dump(body)
  end
  Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }.body
end

# Step 1 — pre-import check: gate on eligible before any create
check = JSON.parse(call(:post, "/numbers/porting/check",
  phoneNumber: "+14155551234", currentCarrier: "Acme Telecom"))
abort("Not portable: #{check["data"]["reasons"].join(", ")}") unless check["data"]["eligible"]

# Step 2 — create the port: draft checkpoint while the LOA is outstanding
port = JSON.parse(call(:post, "/numbers/porting", {
  numbers: ["+14155551234"], currentCarrier: "Acme Telecom", country: "US",
  accountNumber: "998877", authorizedSigner: "Jane Doe",
  serviceAddress: { line1: "1 Market St", city: "San Francisco", state: "CA",
                    postalCode: "94105", countryCode: "US" },
  draft: true,
}))
port_id = port["data"]["id"]

# Step 3 — FOC timeline read: a stored-row read; safe to poll, no carrier call
puts call(:get, "/numbers/porting/#{port_id}/timeline")

# Step 4 — webhook receiver: subscribe once, react to events instead of polling
puts call(:post, "/webhooks", {
  url: "https://yourapp.com/webhooks/orbit",
  events: %w[
    number.ported porting.request.loa_signed porting.request.supplement_submitted
    porting.request.manual_review_required porting.request.cancelled
  ],
})

# Multipart upload (bulk-csv / LOA steps below) with the stdlib:
puts call(:post, "/numbers/port-in/bulk-csv", nil, "port-in-batch.csv")

<?php
$key = getenv("ORBIT_API_KEY");
$base = "https://api.orbit.devotel.io/api/v1";

function call(string $method, string $path, ?array $body = null, ?string $fileField = null): string {
    global $key, $base;
    $ch = curl_init($base . $path);
    $headers = ["X-API-Key: $key"];
    $opts = [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method];
    if ($fileField !== null) {                      // multipart: bulk-csv / LOA uploads
        $opts[CURLOPT_POSTFIELDS] = ["file" => new CURLFile($fileField)];
    } elseif ($body !== null) {
        $headers[] = "Content-Type: application/json";
        $opts[CURLOPT_POSTFIELDS] = json_encode($body);
    }
    $opts[CURLOPT_HTTPHEADER] = $headers;
    curl_setopt_array($ch, $opts);
    $out = curl_exec($ch);
    curl_close($ch);
    return $out;
}

// Step 1 — pre-import check: gate on eligible before any create
$check = json_decode(call("POST", "/numbers/porting/check", [
    "phoneNumber" => "+14155551234", "currentCarrier" => "Acme Telecom",
]), true);
if (($check["data"]["eligible"] ?? false) !== true) {
    exit("Not portable: " . implode(", ", $check["data"]["reasons"]));
}

// Step 2 — create the port: draft checkpoint while the LOA is outstanding
$port = json_decode(call("POST", "/numbers/porting", [
    "numbers" => ["+14155551234"], "currentCarrier" => "Acme Telecom", "country" => "US",
    "accountNumber" => "998877", "authorizedSigner" => "Jane Doe",
    "serviceAddress" => ["line1" => "1 Market St", "city" => "San Francisco", "state" => "CA",
                         "postalCode" => "94105", "countryCode" => "US"],
    "draft" => true,
]), true);
$portId = $port["data"]["id"];

// Step 3 — FOC timeline read: a stored-row read; safe to poll, no carrier call
echo call("GET", "/numbers/porting/$portId/timeline");

// Step 4 — webhook receiver: subscribe once, react to events instead of polling
echo call("POST", "/webhooks", [
    "url" => "https://yourapp.com/webhooks/orbit",
    "events" => ["number.ported", "porting.request.loa_signed",
                 "porting.request.supplement_submitted", "porting.request.manual_review_required",
                 "porting.request.cancelled"],
]);

// Multipart upload (bulk-csv / LOA steps below) with the stdlib:
echo call("POST", "/numbers/port-in/bulk-csv", null, "port-in-batch.csv");

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv \
  -H "X-API-Key: dv_live_sk_..." \
  -F "file=@port-in-batch.csv"

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append(
  "file",
  new Blob([await readFile("port-in-batch.csv")], { type: "text/csv" }),
  "port-in-batch.csv",
);

const res = await fetch("https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv", {
  method: "POST",
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  body: form,
});
console.log(await res.json());

import os

import requests

with open("port-in-batch.csv", "rb") as fh:
    res = requests.post(
        "https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv",
        headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
        files={"file": ("port-in-batch.csv", fh, "text/csv")},
        timeout=30,
    )
print(res.json())

# 1. Upload the LOA (PDF / JPEG / PNG / HEIC, up to 10MB) under the file field
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_draft456/loa \
  -H "X-API-Key: dv_live_sk_..." \
  -F "file=@loa.pdf"

# 2. Record the in-platform signature — moves the LOA from draft to signed
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_draft456/loa/sign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signerName": "Jane Doe",
    "signerEmail": "jane@acme.com",
    "acknowledgement": "I am authorized to request this number be ported to Orbit and the information above is accurate."
  }'

# 3. Forward the signed LOA to the losing carrier — the only call valid in signed
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_draft456/loa/submit \
  -H "X-API-Key: dv_live_sk_..."

import { readFile } from "node:fs/promises";
import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const portId = "port_draft456"; // from step 2 of the four-call loop

// 1. Upload — the SDK request() is JSON-only, so send the multipart via fetch
const form = new FormData();
form.append(
  "file",
  new Blob([await readFile("loa.pdf")], { type: "application/pdf" }),
  "loa.pdf",
);
await fetch(`https://api.orbit.devotel.io/api/v1/numbers/porting/${portId}/loa`, {
  method: "POST",
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  body: form,
});

// 2. Sign — draft → signed; signing twice returns 422
await orbit.request("POST", `/numbers/porting/${portId}/loa/sign`, {
  signerName: "Jane Doe",
  signerEmail: "jane@acme.com",
  acknowledgement:
    "I am authorized to request this number be ported to Orbit and the information above is accurate.",
});

// 3. Submit — signed → submitted; the carrier review clock starts here
await orbit.request("POST", `/numbers/porting/${portId}/loa/submit`, undefined);

import os

import requests
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()
port_id = "port_draft456"  # from step 2 of the four-call loop

# 1. Upload — multipart under the file field
with open("loa.pdf", "rb") as fh:
    requests.post(
        f"https://api.orbit.devotel.io/api/v1/numbers/porting/{port_id}/loa",
        headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
        files={"file": ("loa.pdf", fh, "application/pdf")},
        timeout=30,
    )

# 2. Sign — draft → signed; signing twice returns 422
client.request("POST", f"/numbers/porting/{port_id}/loa/sign", json_body={
    "signerName": "Jane Doe",
    "signerEmail": "jane@acme.com",
    "acknowledgement": "I am authorized to request this number be ported to Orbit and the information above is accurate.",
})

# 3. Submit — signed → submitted; the carrier review clock starts here
client.request("POST", f"/numbers/porting/{port_id}/loa/submit")