Vela Mobile API Documentation

MW API DOC

Port-In

Previous Next

Activate a SIM card by porting an existing phone number from another carrier.

Validate Port-In Eligibility

Pre-check whether an MDN is eligible for port-in before submitting a full port-in request.

Endpoint: GET /sim/port-in/validate/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn path string Yes 10-digit phone number to validate
sim query string No ICCID (alphanumeric, max 25 characters)

Response Schema

Field Type Description
mdn string 10-digit Mobile Number
eligible boolean Whether the MDN is eligible for port-in
status string success or failure
message string Human-readable description
provider_name string Current carrier name (e.g., AT&T Mobility) — only present on success
provider_id string Current carrier ID (e.g., 6214) — only present on success

Response Examples

Eligible (200 OK):

{
  "mdn": "1234567890",
  "eligible": true,
  "status": "success",
  "message": "Eligible",
  "provider_name": "AT&T Mobility",
  "provider_id": "6214"
}

Not Eligible (200 OK):

{
  "mdn": "1234567890",
  "eligible": false,
  "status": "failure",
  "message": "MSISDN not eligible for Port In (GENS-0043)",
  "provider_name": null,
  "provider_id": null
}

Possible Error Codes

GENS-0043, GENS-0161, GENS-0374, GENS-0013

For full error details see Error & Response Codes.

Port-In Request

Submit a port-in request to move a phone number from another carrier.

Endpoint: POST /sim/port-in/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
sim string Yes ICCID to activate (alphanumeric, max 25 chars)
plan_id string Yes Plan ID (must be in user's authorized plans)
mdn string Yes Number to port (10 digits)
account_number string Yes Previous carrier account number
account_pin string Yes Previous carrier PIN/password
first_name string Yes Subscriber first name
last_name string Yes Subscriber last name
address1 string Yes Billing address line 1
address2 string No Billing address line 2
city string Yes City
state string Yes 2-letter US state code
zip_code string Yes 5-digit ZIP code
transaction_id string No Unique transaction ID (auto-generated with PORT_ prefix if not provided)

Request Example

{
  "sim": "89014103211118512345",
  "plan_id": "2063",
  "mdn": "1234567890",
  "account_number": "123456789",
  "account_pin": "1234",
  "first_name": "John",
  "last_name": "Doe",
  "address1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zip_code": "10001",
  "transaction_id": "PORT_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_8694AF90ECDF",
  "message": "INTER",
}

Success with WFC Warning (200 OK):

Port-in submitted but WFC could not be added (E911 address missing or invalid):

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_8694AF90ECDF",
  "message": "SUCCESS",
  "warning": "Portin Completed Successfully: Failed To Add WFC due to E911 address not provided. Please Provide E911 Address and Try add WFC with AddWFC API",
  "wfc_status": false
}

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_8694AF90ECDF",
  "message": "SUCCESS",
  "warning": "Portin Completed Successfully: Failed To Add WFC due to Invalid E911 Address. Please Retry With AddWFC API",
  "wfc_status": false
}

Failure (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_8694AF90ECDF",
  "message": "The MSISDN is already submitted for port-in (GENS-0161)",
  "error": ["The MSISDN is already submitted for port-in (GENS-0161)"]
}

Conflict (409):

{
  "status": "failure",
  "message": "Transaction ID already exists",
  "code": "HTTP_409"
}

Possible Error Codes

GENS-0006, GENS-0030, GENS-0031, GENS-0043, GENS-0050, GENS-0051, GENS-0052, GENS-0054, GENS-0090, GENS-0161, GENS-0170, GENS-0180, GENS-0197, GENS-0289, GENS-0374

For full error details see Error & Response Codes.

Query Port-In Status

Check the current status of a port-in request.

Endpoint: GET /sim/port-in/status/{mdn}

Rate Limit: 60 requests/minute

Authentication: Bearer token required

Request Parameters

Parameter Location Type Required Description
mdn path string Yes 10-digit phone number with a pending port-in

Response Schema

Field Type Description
status string success or failure
mdn string 10-digit Mobile Number
transaction_id string Auto-generated query transaction ID
message string Port status description (INTER, RESOLUTION REQUIRED, COMPLETED)
error array Error details (on failure only)

Note

The message field contains the actual port status from the carrier. Key values to handle:

  • INTER — Port is in progress (inter-carrier transfer)
  • RESOLUTION REQUIRED — Old carrier rejected, needs correction via Modify
  • COMPLETED — Port is done, number is active on your network

Response Examples

In Progress (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "transaction_id": "PORT_QUERY_A1B2C3D4",
  "message": "INTER",
}

Resolution Required (200 OK):

Port-in needs additional information — use Modify Port-In to update:

{
  "status": "success",
  "mdn": "1234567890",
  "transaction_id": "PORT_QUERY_A1B2C3D4",
  "message": "RESOLUTION REQUIRED",
}

Completed (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "transaction_id": "PORT_QUERY_A1B2C3D4",
  "message": "COMPLETED",
}

No Port Found (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "transaction_id": "PORT_QUERY_A1B2C3D4",
  "message": "No Port-In request found for the MSISDN provided. (GENS-0041)",
  "error": ["No Port-In request found for the MSISDN provided. (GENS-0041)"]
}

Port Already Cancelled (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "transaction_id": "PORT_QUERY_A1B2C3D4",
  "message": "The port-in request for this number was cancelled. Please submit a new port-in request. (GENS-0048)",
  "error": ["The port-in request for this number was cancelled. Please submit a new port-in request. (GENS-0048)"]
}

Possible Error Codes

GENS-0041, GENS-0047, GENS-0048, GENS-0049

Carrier status/rejection codes: 1B, 1C, 1E, 1L, 1M, 1N, 1P, 6A, 6B, 6C, 6D, 6E, 6F, 6G, 6H, 6J, 6K, 6L, 6M, 6N, 6P, 6R, 7A

For full error details see Error & Response Codes and Port-In Status / Rejection Codes.

Modify Port-In

Update details of a pending port-in request. Typically used when the port status is "Resolution Required" (e.g., incorrect account number, name mismatch).

Endpoint: POST /sim/port-in/modify/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Warning

A port-in can only be modified when its status is "Resolution Required". If the port is already in-progress, you will receive error GENS-0049.

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
sim string Yes ICCID (alphanumeric, max 25 chars)
agent_account string No Admin/agent account ID
order_id string No Port-in order ID
authorized_by string No Authorizing person name
business_name string No Business name
old_account string No Old provider account number
old_password string No Old provider PIN/password
old_ssn string No Last 4 of SSN (old provider)
old_dob string No Date of birth (YYYY-MM-DD)
first_name string No Subscriber first name
last_name string No Subscriber last name
address1 string No Billing address line 1
address2 string No Billing address line 2
city string No City
state string No 2-letter state code
zip_code string No 5-digit ZIP code
transaction_id string No Unique transaction ID (auto-generated with PORT_MOD_ prefix if not provided)

Request Example

{
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "old_account": "987654321",
  "old_password": "5678",
  "first_name": "John",
  "last_name": "Doe",
  "address1": "456 Oak Ave",
  "city": "Houston",
  "state": "TX",
  "zip_code": "77001",
  "transaction_id": "PORT_MOD_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_MOD_TX123",
  "message": "INTER",
}

Success with WFC Warning (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_MOD_TX123",
  "message": "SUCCESS",
  "warning": "UpdatePort Completed Successfully: Failed To Add WFC due to Invalid E911 Address. Please Retry With AddWFC API",
  "wfc_status": false
}

Cannot Modify (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_MOD_TX123",
  "message": "PortIn request is pending and no modifications are required at this time (GENS-0049)",
  "error": ["PortIn request is pending and no modifications are required at this time (GENS-0049)"]
}

SIM Mismatch (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_MOD_TX123",
  "message": "SIM passed for UpdatePortIn request does not match with original PortIN request. (GENS-0125)",
  "error": ["SIM passed for UpdatePortIn request does not match with original PortIN request. (GENS-0125)"]
}

Possible Error Codes

GENS-0041, GENS-0049, GENS-0050, GENS-0051, GENS-0052, GENS-0090, GENS-0125, GENS-0289, GENS-0417, GENS-0425

For full error details see Error & Response Codes.

Cancel Port-In

Cancel a pending port-in request.

Endpoint: POST /sim/port-in/cancel/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes 10-digit Mobile Number
sim string Yes ICCID (alphanumeric, max 25 chars)
transaction_id string No Unique transaction ID (auto-generated with PORT_CANCEL_ prefix if not provided)

Request Example

{
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_CANCEL_TX123"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_CANCEL_TX123",
  "message": "PortIn request cancelled successfully",
}

No Port Found (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_CANCEL_TX123",
  "message": "No Port-In request found for the MSISDN provided. (GENS-0041)",
  "error": ["No Port-In request found for the MSISDN provided. (GENS-0041)"]
}

Already Cancelled (400 Bad Request):

{
  "status": "failure",
  "mdn": "1234567890",
  "sim": "89014103211118512345",
  "transaction_id": "PORT_CANCEL_TX123",
  "message": "The port-in request for this number was cancelled. Please submit a new port-in request. (GENS-0048)",
  "error": ["The port-in request for this number was cancelled. Please submit a new port-in request. (GENS-0048)"]
}

Possible Error Codes

GENS-0041, GENS-0048, GENS-0012

For full error details see Error & Response Codes.

Port-In with MDN Change (Conversion)

Port a new phone number onto an existing subscriber's SIM, replacing the current MDN. Used when a subscriber wants to keep their SIM but switch to a number ported from another carrier.

Endpoint: POST /sim/port-in/convert/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field Type Required Description
mdn string Yes Current MDN on the SIM (10 digits)
new_mdn string Yes MDN to port in from other carrier (10 digits)
sim string Yes Current ICCID
plan_id string Yes Plan ID (must be in user's authorized plans)
zip_code string Yes Service ZIP (5 digits or ZIP+4)
authorized_by string Yes Authorized person name
first_name string Yes Subscriber first name
last_name string Yes Subscriber last name
address1 string Yes Billing address line 1
city string Yes City
state string Yes 2-letter US state code
account_number string Yes Old carrier account number
account_pin string Yes Old carrier PIN/password
address2 string No Billing address line 2
e911_address1 string No E911 street address
e911_address2 string No E911 street address line 2
e911_city string No E911 city
e911_state string No E911 state
e911_zip string No E911 ZIP code
transaction_id string No Unique transaction ID (auto-generated with PORT_CONVERT_ prefix if not provided)

Request Example

{
  "mdn": "5550199888",
  "new_mdn": "2125550100",
  "sim": "89014103211118500000",
  "plan_id": "2037",
  "zip_code": "10001",
  "authorized_by": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "address1": "123 Main St",
  "address2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "account_number": "987654321",
  "account_pin": "1234",
  "e911_address1": "123 Main St",
  "e911_city": "New York",
  "e911_state": "NY",
  "e911_zip": "10001"
}

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "2125550100",
  "sim": "89014103211118500000",
  "transaction_id": "PORT_CONVERT_8694AF90ECDF",
  "message": "SUCCESS",
}

Success with WFC Warning (200 OK):

{
  "status": "success",
  "mdn": "2125550100",
  "sim": "89014103211118500000",
  "transaction_id": "PORT_CONVERT_8694AF90ECDF",
  "message": "Success",
  "warning": "Portin Completed Successfully: Failed To Add WFC due to Invalid E911 Address. Please Retry With AddWFC API",
  "wfc_status": false
}

Failure (400 Bad Request):

{
  "status": "failure",
  "mdn": "2125550100",
  "sim": "89014103211118500000",
  "transaction_id": "PORT_CONVERT_8694AF90ECDF",
  "message": "The MSISDN is not eligible for Port In (GENS-0043)",
  "error": ["The MSISDN is not eligible for Port In (GENS-0043)"]
}

Possible Error Codes

GENS-0006, GENS-0013, GENS-0043, GENS-0050, GENS-0051, GENS-0054, GENS-0090, GENS-0161, GENS-0170, GENS-0180, GENS-0250, GENS-0289, GENS-0374

For full error details see Error & Response Codes.

Port-Out Validation

Looking for port-out?

Port-out validation is handled via a webhook callback, not an API you call directly. When another carrier requests to port out one of your subscribers, Vela Mobile forwards the request to your application for an approve/deny decision.

See Callbacks → Port-Out Validation for full details on setting up your webhook, the JSON payloads you'll receive, and the decision codes you can return.

Common HTTP Errors (All Port Endpoints)

HTTP Code Meaning
400 Bad request / upstream carrier operation failed
401 Not authenticated (missing or invalid Bearer token)
403 Forbidden (insufficient permissions or unauthorized plan)
409 Conflict (duplicate transaction_id)
422 Validation error (invalid state code, ZIP format, MDN format)
429 Rate limit exceeded
500 Internal server error

Full error reference: Error & Response Codes

Activations Plans