Skip to content
vocapable.Docs

Start a port-in request (the guided LOA)

POST
/v1/workspace/numbers/port-ins
curl --request POST \
  --url https://api.vocapable.com/v1/workspace/numbers/port-ins \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "numbers": [ { "phone_e164": "example", "pin": "example" } ], "customer_type": "Business", "business_name": "example", "authorized_representative": "example", "authorized_representative_email": "example", "account_telephone_number": "example", "account_number": "example", "service_address": { "street": "example", "street_2": "example", "city": "example", "state": "example", "zip": "example" }, "target_port_in_date": "2026-04-15" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
<= 255 characters

Unique key for this request, so a retry replays the original result instead of repeating the work. Stored for 24 hours; a replayed response carries Idempotent-Replay: true. A UUID is the documented shape. Required on this endpoint: a retry without one would dial a human twice or spend money twice.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
WorkspacePortInCreate

The guided LOA. Twilio generates the Letter of Authorization from these facts and emails it to the authorized representative to sign.

object
numbers
required
Numbers
Array<object>
>= 1 items <= 20 items
WorkspacePortInNumberInput
object
phone_e164
required
Phone E164
string
/^\+1[2-9]\d{9}$/
pin
Any of:
string
>= 1 characters <= 20 characters
customer_type
Customer Type
string
default: Business
Allowed values: Business Individual
business_name
required
Business Name
string
>= 1 characters <= 100 characters
authorized_representative
required
Authorized Representative
string
>= 3 characters <= 100 characters
authorized_representative_email
required
Authorized Representative Email
string
>= 3 characters <= 254 characters
account_telephone_number
required
Account Telephone Number
string
/^\+[1-9]\d{7,14}$/
account_number
required
Account Number
string
>= 1 characters <= 40 characters
service_address
required
WorkspacePortInAddress
object
street
required
Street
string
>= 1 characters <= 100 characters
street_2
Any of:
string
<= 100 characters
city
required
City
string
>= 1 characters <= 60 characters
state
required
State
string
/^[A-Z]{2}$/
zip
required
Zip
string
/^\d{5}(-\d{4})?$/
target_port_in_date
required
Target Port In Date
string format: date

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
WorkspacePortIn
object
id
required
Id
string
stage
required
Stage
string
Allowed values: draft submitting waiting_for_signature submitted in_progress action_required canceling completed canceled failed
numbers
required
Numbers
Array<object>
WorkspacePortInNumber
object
phone_e164
required
Phone E164
string
status
required
Status
string
rejection_reason
required
Any of:
string
pin_on_file
required
Pin On File
boolean
business_name
required
Business Name
string
authorized_representative
required
Authorized Representative
string
authorized_representative_email
required
Authorized Representative Email
string
service_address_summary
required
Service Address Summary
string
account_number_hint
required
Any of:
string
bill_uploaded
required
Bill Uploaded
boolean
target_port_in_date
required
Any of:
string format: date
twilio_status
required
Any of:
string
signature_request_url
required
Any of:
string
last_error
required
Any of:
string
forwarding_guidance
required
Forwarding Guidance
string
can_submit
required
Can Submit
boolean
can_cancel
required
Can Cancel
boolean
revision
required
Revision
integer
submitted_at
required
Any of:
string format: date-time
last_checked_at
required
Any of:
string format: date-time
completed_at
required
Any of:
string format: date-time
created_at
required
Created At
string format: date-time
Example
{
  "stage": "draft"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}