Technical Guide

Core concepts

Request: An HTTP POST to https://connect.plumma.it/services/api with a JSON body. The body holds the phone number, the list of commands to run on it, and any extra input that some commands need, such as the data to match for kyc_match. One request covers one number.
Command: A named check, such as sim_swap or current_carrier, listed in the commands array. Commands are synchronous. You can send several in one request, and each served command fills its own block in the response.
Response: One JSON object for the whole request. It holds a status, a status_message, the version of the model, and one block for each command that was served. A block whose command was not requested or not served is left out, never sent as null.
Status: The outcome of the request as a whole: 0 all served, 4 partial, 2 nothing available in the number's country, 3 no command name recognized, 5 not completed. An invalid request, including an invalid number, gets HTTP 400 instead of a status. See Billing for what each one costs.
Model version: Every response carries the version of the request and response model that produced it. It matches the version shown at the top of this reference.
Date and time: Timestamps follow ISO 8601 and are in UTC, for example 2026-09-14T08:30:00.000Z. Some sources know only the day of an event. In that case the time is midnight UTC, and the field that goes with it says how precise the value is (for example ported_date_type).

Request format

Field	Required	Description
`number`	Always	The phone number in international format, with or without a leading `+`. It is normalized to E.164 and checked against its country's numbering plan. An invalid number gets `400`.
`commands`	Always	A non-empty list of command names, each listed once. A name that is not a Plumma® Connect command is not run, not charged, and named in `status_message`.
`kyc_challenges`	For `kyc_match`	The data to match: name, date of birth, email, and an address, either structured (`address`) or free text (`inline_address`). See `kyc_match`.
`location_area`	For `location_verification`	The area to check against: `latitude`, `longitude`, `radius`, and optionally `max_age`. Without a complete area the command returns no data and is not charged.

An invalid request gets 400 with application/problem+json, and the detail field says what is wrong. No operator is contacted and nothing is charged. A JSON Schema for the request, plmrequest.schema.json, is published next to this reference.

Commands

The tables below list each command and the response field it fills. Which commands are available depends on the number's country. The API reference documents every field and every value.

Number and network intelligence

Command	What it tells you	Response field
`line_classification`	The kind of line behind the number, for example mobile or fixed, plus a more detailed network classification.	`type`, `etype`
`current_carrier`	The operator currently serving the number.	`current_carrier` (MCC, MNC, name, SPID, LRN, OCN)
`issuing_carrier`	The operator that originally issued the number.	`issuing_carrier` (MCC, MNC, name, SPID, OCN)
`porting_timestamp`	Whether the number was ported, and when it last was.	`ported`, `ported_date`, `ported_date_type`
`porting_logs`	The porting events known for the number.	`porting_logs` (list)
`network_presence`	Whether the number is currently registered on a network.	`present`
`roaming_intel`	Whether the number is roaming, and on which network.	`is_roaming`, `roaming_network`
`commercial_segment`	The subscriber's contract type, for example prepaid, postpaid or business.	`market_segment`
`deactivation_point`	The most recent deactivation event for the number.	`churn_tracker`
`churn_tracker`	The recent deactivation events for the number.	`churn_tracker` (list)

Identity and fraud

Command	What it tells you	Response field
`sim_swap`	How recently the SIM card behind the number was changed. A recent change is a strong sign of account takeover.	`simswap` (`risk_indicator`, time window, date)
`device_swap`	How recently the device using the number was changed.	`device_swap` (`risk_indicator`, time window, date)
`port_fraud_shield`	Whether recent porting activity on the number looks fraudulent.	`portfraud`
`divert_detector`	Whether unconditional call forwarding is active on the number.	`divert_detector`
`digital_footprint`	Whether the number is registered on a set of online platforms.	`digital_footprint` (one value per platform)
`age_verification`	Whether the subscriber is above an age threshold.	`age_verification` (`verified`, `threshold`)
`kyc_match`	How closely the data you send (name, date of birth, address, email) matches what the operator holds. The operator's data is never returned, only a score from 0 to 100 for each element.	`kyc_results`

Location

Command	What it tells you	Response field
`location_verification`	Whether the device is inside the area you send in `location_area`.	`location_verification`
`location_retrieval`	The approximate position of the device, as an area.	`device_location`

Negative values are answers

In several blocks, a negative value means the operator answered without giving a usable result. For example, risk_indicator: -1 means "no data held for this number". Such a value is an answer, and it is charged. A command that got no answer at all has no block in the response, and it is not charged.

Rate limits

Each API key can send up to 900 requests per minute, about 15 per second on average. The limit is counted over a one-minute window, so a short burst above 15 per second is allowed as long as the total for the minute stays within the limit. Above it, requests are refused with HTTP 429 and a Retry-After header that gives the number of seconds to wait.

If you need a higher limit, contact Plumma.

Usage and spending in the console

The console has two views of your traffic:

Statistics: your calls grouped by command and by outcome, filtered by period and by country.
Controlling: what you spend, broken down by organization and by application, and how your calls ended.

Calls to demo numbers are free and do not appear in what you spend.

Tools and code generation

No official SDK is available yet. The OpenAPI 3.1 descriptor at the top of this page can be imported into Postman, Insomnia and other HTTP clients. You can also feed it to an OpenAPI code generator to produce a typed client in your language.

Webhooks and asynchronous notifications

Every command is synchronous: the result is in the response to your request. No webhooks or asynchronous notifications exist today.