Submits a number porting request to bring a phone number from another carrier into Telgea. The user must have an existing plan in INACTIVE or PORTING status.

Important constraints:

• The executionDate must be one of the type's executionDate.dates from GET /v1/port-ins/fields/{countryCode}, which hold until its validUntil. The date is checked once everything else passes: a date outside them is then refused with 400 BAD_REQUEST, and no port-in is created.
• Only one port-in can be in progress per phone number at a time. Submitting a port-in for an MSISDN that already has an active (non-completed, non-failed, non-rejected) port-in will be rejected.
• A number already with Telgea cannot be ported in: one on a Telgea line, or one whose plan ended within the last 14 days and can still be restored. It is refused with 409 CONFLICT.

Recommended flow:

1. Call GET /v1/port-ins/fields/{countryCode} to discover required fields for the country
2. Call POST /v1/port-ins/validate to verify the data before submission
3. Call this endpoint to submit the port-in

If provider-side validation fails, the response will have status: "REJECTED" with an errors array describing the issues. A successful submission returns status: "CREATED".

The port-in will progress through states: CREATED → SUBMITTED → ACCEPTED → SUCCEEDED. Check the status with GET /v1/port-ins/{portInId}.

Retrying a port-in that ended in REJECTED or FAILED: read failure.reason and failure.field on the port-in, correct what they point at (failure.text explains it in words you can show your customer), then call this endpoint again with the same msisdn. The failed attempt is kept as history and stays readable at its own id — GET /v1/port-ins/number/{numberId} lists every attempt for the number, newest first. A retry sent while a port-in for that number is still in flight is refused with 409 CONFLICT — a number can only be ported once at a time anywhere. Wait for it to finish, then read failure.reason and submit again.

{
  "userId": "9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01",
  "countryCode": "DE",
  "msisdn": "+4915112345678",
  "executionDate": "2027-03-01",
  "type": "personal",
  "fields": {
    "currentCarrier": "CONG",
    "authorizationCode": "1985-04-12",
    "ownerFirstName": "Erika",
    "ownerLastName": "Mustermann",
    "isUnlocked": true
  }
}

{
  "id": "c3d4e5f6-a7b8-9012-c345-678901234567",
  "status": "CREATED",
  "msisdn": "+4915112345678",
  "numberId": "8238c1b9-c2c0-4455-9b03-4bd787052709",
  "executionDate": "2027-03-01",
  "errors": [
    {
      "message": "A PAC is 3 letters, then 6 digits (e.g. ABC123456). 6 digits then 3 letters is a STAC, not a PAC.",
      "field": "authorizationCode",
      "code": "FORMAT_INVALID"
    }
  ]
}