Billing

The rule

You pay for each command an operator serves, not for each API call. Everything else in this section follows from that.

• One request can ask for several commands. Each one is counted and charged separately.
• A command is charged only when an operator answers it. An answer can be negative, for example "this operator holds no data for this number" (risk_indicator: -1 on sim_swap). That still counts as an answer, and it is charged.
• A command costs nothing when it is not served: when it is not available in the number's country, when the operator could not be reached or did not answer, or when the command name is not one Plumma® Connect recognizes.
• There is no flat fee per call. A request with three served commands counts as three units. A request where nothing could be served counts as zero.

How a command is billed

Each command in a request goes through these steps on its own, so a single call can contain both charged and free commands.

Request (one or more commands)
      |
      v
Is the request valid?  --------------------- No --->  HTTP 400, not billed
      |                                                (invalid number or payload)
     Yes
      v
Is the command name recognized?  ----------- No --->  not billed
      |
     Yes
      v
Is the command available in the
number's country?  ------------------------- No --->  not billed
      |                                                (no operator is contacted)
     Yes
      v
Sent to an operator
      |
      v
Did the operator answer?  ------------------ No --->  not billed
      |
     Yes (including "no data")
      v
1 billable unit

Reading status and status_message

Every response has a numeric status and a plain-language status_message. The status is the field to rely on. The status_message is for people: its wording can change, and it names the commands that were not served.

A request that fails validation, including one with an invalid phone number, gets HTTP 400 and no status at all. It never reaches an operator and is never charged.

Examples

One command, served: 1 unit

A covered UK mobile number, command sim_swap.

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

Two commands, one not available: 1 unit

An Italian number, commands sim_swap and porting_logs, where porting_logs is not offered in Italy.

{
  "status": 4,
  "status_message": "Response from one supplier - Commands [porting_logs] not available in [IT]",
  ...
}

You pay for sim_swap only.

Command sent to an operator, no data returned: not billed

{
  "status": 4,
  "status_message": "Response from one supplier - Commands [kyc_match] were routed but returned no data",
  ...
}

You pay for the other commands that were served, and nothing for kyc_match. When the operator gave a reason, the message includes it in brackets.

Country not covered: not billed

{
  "status": 2,
  "status_message": "No commands available in country [XX]"
}

No operator was contacted, and nothing is charged.

Command name not recognized: not billed

{
  "status": 3,
  "status_message": "Unsupported command: [sim_swapp]"
}

Invalid number: not billed

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "status": 400,
  "detail": "...",
  ...
}

Demo number: never billed

{
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only",
  ...
}

Testing is free

Calls about demo numbers are never charged. You use the same key and the same endpoint as for real numbers. You can recognize these responses because their status_message ends with This response is for demo purpose only. They have the same structure as live responses, so you can build and test your integration end to end without paying for it.

Countries without coverage

Asking for a command in a country where it is not available returns status: 2 (or 4, if other commands in the same request were served) and costs nothing. Large volumes of numbers from countries without coverage do not generate charges.

One exception: some commands are offered worldwide, whatever the number's country. A worldwide command is always routed, and it is charged when an operator answers it. The free "country not covered" outcome applies only to commands that are tied to specific countries.

Quick reference