porting_timestamp

porting_timestamp tells you whether a phone number has been ported to another operator and, if so, when it was last ported.

A recent port is a fraud signal in its own right: moving a number to a new operator is one of the ways to take control of it. For the operator the number is on today, use current_carrier; for the full history of ports, use porting_logs.

Request

Send the number and porting_timestamp in commands. No other input is needed.

{
  "number": "+447808226974",
  "commands": ["porting_timestamp"]
}

porting_timestamp is not available in every country. Where it is not available, see Billing.

Response

The result is in three fields at the top level of the response.

A ported number:

{
  "status": 0,
  "status_message": "Response from one supplier",
  "ported": true,
  "ported_date": "2024-01-15T00:00:00.000Z",
  "ported_date_type": "exact",
  "version": "..."
}

A number that has never been ported:

{
  "status": 0,
  "status_message": "Response from one supplier",
  "ported": false,
  "version": "..."
}

Field	Type	Meaning
`ported`	boolean	`true` if the number has been ported at least once, `false` if it never has. A number ported away and later back to its original operator still reads `true`.
`ported_date`	string	When the number was last ported, ISO 8601 in UTC. When the source knows only the day, the time is midnight UTC (`2024-01-15T00:00:00.000Z`): read `ported_date_type` to know how precise the date is. Absent when the number has not been ported.
`ported_date_type`	string	How precise `ported_date` is, as stated by the source. Present only together with `ported_date`.

ported_date_type values

Value	Meaning
`exact`	`ported_date` is the actual day of the port.
`before`	The number was ported on or before `ported_date`, which marks the start of the records available for that country: the actual port may be older.

Compare ported_date_type without regard to case, and treat any other value as "precision unknown".

When there is no porting information

If the source has no porting data for the number or could not be reached, the response has none of these fields. The status is 4, and the status_message names porting_timestamp among the commands that returned no data. If the number's country is not covered, the status is 2, or 4 when other commands were served.

Billing

A response with ported or ported_date is charged, including ported: false: "never ported" is an answer. A response with neither is not charged.

API reference

Request

curl -X POST "https://api.connect.plumma.it/services/api" \
-H "Content-Type: application/json" \
-H "x-plumma-connect-api-key: YOUR_API_KEY_HERE" \
-H "x-plumma-connect-app-id: YOUR_APP_ID_HERE" \
-d '{
  "number": "+16469817679",
  "commands": [
    "porting_timestamp"
  ]
}'

Response (exact date)

{
  "number": "+918431863691",
  "ported_date": "2017-04-21",
  "ported_date_type": "exact",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=64] [{porting_timestamp=SUPPLIER0 : Success}]",
  "version": "1.0.2-20260608095239"
}

Response (before onboarding)

{
  "number": "+447700900456",
  "ported_date": "2015-01-01",
  "ported_date_type": "before",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=64] [{porting_timestamp=SUPPLIER0 : Success}]",
  "version": "1.0.2-20260608095239"
}

Response (never ported)

{
  "number": "+390612345678",
  "ported_date": null,
  "ported_date_type": null,
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=64] [{porting_timestamp=SUPPLIER0 : Success}]",
  "version": "1.0.2-20260608095239"
}

Response (uncovered territory)

{
  "number": "+34611222333",
  "ported_date": "n/a",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=64] [{porting_timestamp=SUPPLIER0 : Success}]",
  "version": "1.0.2-20260608095239"
}