Callbacks - Vela Mobile API Documentation

Callback webhooks notify your application about carrier-initiated events. You provide a webhook URL to Vela Mobile, and the API sends JSON requests to it.

Port-Out Validation

When another carrier requests to port out one of your subscribers, Vela Mobile sends a JSON request to your webhook. Your app evaluates the request and returns an approve or deny decision.

Webhook Request

Your application receives a POST request with this JSON body:

{
  "mdn": "5551234567",
  "osp_account_number": "1234567",
  "sim": "89012345",
  "imei": "123456789012345",
  "name": "John Doe",
  "osp_account_password": "pass123",
  "address": {
    "street1": "123 Main St",
    "street2": "Apt 4",
    "city": "Houston",
    "state": "TX",
    "zip_code": "77001"
  }
}

Field	Type	Always Present	Description
`mdn`	string	Yes	10-digit phone number being ported out
`osp_account_number`	string	Yes	7-digit Customer ID
`sim`	string	No	SIM ICCID
`imei`	string	No	Device IMEI
`name`	string	No	Subscriber name
`osp_account_password`	string	No	Account password
`address`	object	No	Subscriber address
`address.street1`	string	No	Street address line 1
`address.street2`	string	No	Street address line 2
`address.city`	string	No	City
`address.state`	string	No	2-letter state code
`address.zip_code`	string	No	5-digit ZIP code

Webhook Response

Respond with HTTP 200 and a JSON body containing your decision:

{
  "message_code": "7A",
  "description": "MDN_OK"
}

Field	Type	Required	Description
`message_code`	string	Yes	Decision code (see below)
`description`	string	Yes	Human-readable description

Decision Codes

Code	Description	Meaning
`7A`	`MDN_OK`	Approve — allow the port-out
`6A`	`MDN_NOT_FOUND`	Deny — MDN not found
`6D`	`MDN_NOT_ACTIVE`	Deny — MDN not active
`8A`	`ACCOUNT_NUM_REQ_OR_INCORRECT`	Deny — account number issue
`8C`	`PASS_PIN_REQ_OR_INCORRECT`	Deny — password/PIN issue
`8D`	`ZIP_CODE_REQ_OR_INCORRECT`	Deny — ZIP code issue

Default Deny

If your app is unreachable, returns an error, times out, or responds with an invalid message_code, the default is deny (6A / MDN_NOT_FOUND).

Confirmation Notification

After the decision is processed, Vela Mobile sends a second POST to your webhook URL:

{
  "event": "port_out_confirmation",
  "mdn": "5551234567",
  "sim": "89012345",
  "message_code": "7A",
  "description": "MDN_OK",
  "confirmed": true,
  "transaction_id": "PORTOUT_abc123def456"
}

Field	Type	Description
`event`	string	Always `port_out_confirmation`
`mdn`	string	Phone number
`sim`	string	SIM ICCID (if available)
`message_code`	string	The decision that was submitted
`description`	string	Decision description
`confirmed`	boolean	`true` if the carrier accepted the decision
`transaction_id`	string	Unique transaction ID (`PORTOUT_` prefix)

Note

If the confirmation notification fails, it does not affect the port-out decision. The failure is logged internally.

Setup

To receive port-out validation requests, provide your webhook URL to Vela Mobile.

Your webhook URL should:

Accept POST requests with Content-Type: application/json
Be reachable over HTTPS
Respond within 30 seconds

Example: https://yourapp.example.com/webhooks/port-out

Both the initial validation request and the confirmation notification are sent to this same URL. Use the event field (port_out_confirmation) in the confirmation payload to distinguish between the two.

Tip

Contact Vela Mobile to register your webhook URL. Once configured, port-out validation requests will start arriving automatically whenever another carrier initiates a port-out for one of your subscribers.