Activations - Vela Mobile API Documentation

Endpoints to activate new SIM cards and provision services.

Single Activation

Activate a single SIM card.

Endpoint: POST /sim/activate/

Rate Limit: 30 requests/minute

Authentication: Bearer token required

Request Body

Field	Type	Required	Description
`sim`	string	Yes	19/20 digit ICCID
`plan_id`	string	Yes	ID of the plan to activate (must be in user's authorized plans)
`zip_code`	string	Yes	US ZIP code — 5 digits (e.g., 33101) or ZIP+4 format (e.g., 33101-1234)
`address1`	string	Yes	Street address (Required for E911/WFC)
`city`	string	Yes	City (Required for E911/WFC)
`state`	string	Yes	Two-letter US state code (e.g., TX, CA, FL, NY) — must be uppercase
`is_esim`	string	No	"Y" or "N" (default "N")
`email`	string	Conditional	Required if `is_esim` is "Y"
`billing_code`	string	No	Optional billing code
`language`	string	No	"ENGL" or "SPAN" (default "ENGL")
`address2`	string	No	Street address line 2
`transaction_id`	string	No	Unique ID (auto-generated with `ACT_` prefix if not provided)

Request Example

{
  "sim": "89014103211118500000",
  "plan_id": "2037",
  "zip_code": "33101",
  "address1": "123 Main St",
  "city": "Miami",
  "state": "FL",
  "is_esim": "N",
  "transaction_id": "ACT_TX123"
}

Validation Rules

state: Must be exactly 2 uppercase letters (e.g., TX, CA, FL, NY)
zip_code: Must be 5 digits (e.g., 33101) or ZIP+4 format (e.g., 33101-1234)
Invalid formats will return 422 Unprocessable Entity

Response Examples

Success (200 OK):

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "customer_id": "380198219",
  "transaction_id": "ACT_8694AF90ECDF",
  "message": "Success"
}

Success with WFC Warning (200 OK) — Missing E911:

{
  "status": "success",
  "mdn": "5550199888",
  "sim": "89014103211118500000",
  "customer_id": "380198219",
  "transaction_id": "ACT_8694AF90ECDF",
  "message": "Success",
  "warning": "Activation 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
}

Success with WFC Warning (200 OK) — Invalid E911:

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

Common Errors (400 Bad Request):

{
  "status": "failure",
  "sim": "89014103211118500000",
  "transaction_id": "ACT_C3223D3BA429",
  "message": "ESN already active with another MDN (914)"
}

{
  "status": "failure",
  "sim": "89014103211118500000",
  "transaction_id": "ACT_15A67629B36B",
  "message": "ESN does not belong to this MVNO (910)"
}

{
  "status": "failure",
  "sim": "89014103211118500000",
  "transaction_id": "ACT_BA3B710DB6A9",
  "message": "Invalid Zipcode. (510)"
}

{
  "status": "failure",
  "sim": "89014103211118500000",
  "transaction_id": "ACT_00627C3E7BC3",
  "message": "Invalid ESN (506)"
}

Authorization Error (403 Forbidden):

{
  "status": "failure",
  "message": "Plan ID '124' is not authorized for user XXX.",
  "code": "HTTP_403"
}

Idempotency Error (409 Conflict):

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

Validation Error (422 Unprocessable Entity):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "state"],
      "msg": "Value error, State must be a 2-letter US state code (e.g., TX, CA, NY)"
    }
  ]
}

Possible Error Codes

(914), (910), (510), (506), (906), GENS-0006, GENS-0011, GENS-0030, GENS-0031, GENS-0090, GENS-0180, GENS-0184, GENS-0197, GENS-0289

For full error details see Error & Response Codes.

Bulk Activation

Activate multiple SIM cards in a single request. Each SIM is processed sequentially with individual success/failure tracking.

Endpoint: POST /sim/activate/bulk/

Rate Limit: 10 requests/hour

Authentication: Bearer token required

Request Body

Field	Type	Required	Description
`activations`	array	Yes	List of activation objects (same fields as single activation)
`transaction_id`	string	No	Optional batch-level transaction ID

Each item in activations uses the same fields as Single Activation.

Request Example

{
  "activations": [
    {
      "sim": "89014103211118500001",
      "plan_id": "2037",
      "address1": "123 Main St",
      "city": "Houston",
      "state": "TX",
      "zip_code": "77001",
      "is_esim": "N"
    },
    {
      "sim": "89014103211118500002",
      "plan_id": "2037",
      "address1": "456 Oak Ave",
      "city": "Dallas",
      "state": "TX",
      "zip_code": "75001",
      "is_esim": "N"
    }
  ]
}

Response Examples

Mixed Results (200 OK):

{
  "results": [
    {
      "sim": "89014103211118500001",
      "status": "success",
      "transaction_id": "BULK_89014103211118500001_1714567890.0",
      "mdn": "2815550199",
      "message": "Success"
    },
    {
      "sim": "89014103211118500002",
      "status": "failure",
      "transaction_id": "BULK_89014103211118500002_1714567890.1",
      "message": "ESN does not belong to this MVNO (910)",
      "error": ["ESN does not belong to this MVNO (910)"]
    }
  ],
  "total": 2,
  "processed": 2
}

Important Notes

Each SIM is activated sequentially (not in parallel).
Plan authorization is checked per-SIM. Unauthorized plans are skipped with a failure entry.
Transaction ID idempotency is enforced per-SIM.
A failure on one SIM does not stop processing of remaining SIMs.

Possible Error Codes

Same as Single Activation — errors are reported per-SIM in the results array.

Common HTTP Errors (All Endpoints on This Page)

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, SIM format)
429	Rate limit exceeded
500	Internal server error

Full error reference: Error & Response Codes