{
  "openapi": "3.0.3",
  "info": {
    "title": "Mobile Intel API",
    "version": "1",
    "description": "Look up US and Canadian (+1) phone numbers: line type, carrier, region and a valid, risky or invalid verdict. Every call needs your API key in the X-API-Key header and a real User-Agent header."
  },
  "servers": [
    {
      "url": "https://mobileintelapi.com"
    }
  ],
  "tags": [
    {
      "name": "Lookup"
    },
    {
      "name": "Service"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your API key from the dashboard."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "detail": {
            "description": "What went wrong.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            ]
          }
        }
      },
      "Result": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "phone": {
            "type": "string",
            "description": "The number you sent, normalised to E.164 when it is a valid +1 number."
          },
          "phone_valid": {
            "type": "boolean"
          },
          "phone_type": {
            "type": "string",
            "enum": [
              "mobile",
              "fixed_line",
              "voip",
              "toll_free",
              "premium_rate",
              "unknown"
            ],
            "nullable": true
          },
          "phone_region": {
            "type": "string",
            "nullable": true
          },
          "country": {
            "type": "string",
            "nullable": true
          },
          "country_code": {
            "type": "string",
            "nullable": true
          },
          "country_prefix": {
            "type": "string",
            "nullable": true
          },
          "international_number": {
            "type": "string",
            "nullable": true,
            "description": "Display format, like +1 416-967-0000."
          },
          "local_number": {
            "type": "string",
            "nullable": true,
            "description": "Display format, like (416) 967-0000."
          },
          "e164": {
            "type": "string",
            "nullable": true,
            "description": "Normalised. Use this (or the input position) to match results."
          },
          "carrier": {
            "type": "string",
            "nullable": true,
            "description": "The carrier the number block was first allocated to. Ported numbers can show the old carrier."
          },
          "mode": {
            "type": "string",
            "example": "static"
          },
          "timezone": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "geographical": {
            "type": "boolean",
            "nullable": true
          },
          "verdict": {
            "type": "string",
            "enum": [
              "valid",
              "risky",
              "invalid"
            ]
          },
          "reasons": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Why the verdict was given."
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/verify": {
      "get": {
        "summary": "Look up one number",
        "operationId": "verifyNumber",
        "tags": [
          "Lookup"
        ],
        "description": "Looks up one +1 number. Send it as E.164 with the plus URL-encoded (`%2B1...`), or as 10 bare digits.",
        "parameters": [
          {
            "name": "number",
            "in": "query",
            "required": true,
            "description": "A +1 (NANP) number: `+14169670000` (encode the + as %2B) or `4169670000`.",
            "schema": {
              "type": "string"
            },
            "example": "+14169670000"
          }
        ],
        "responses": {
          "200": {
            "description": "Lookup result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Result"
                },
                "example": {
                  "status": "success",
                  "phone": "+14169670000",
                  "phone_valid": true,
                  "phone_type": "fixed_line",
                  "phone_region": "Toronto, ON",
                  "country": "Canada",
                  "country_code": "CA",
                  "country_prefix": "1",
                  "international_number": "+1 416-967-0000",
                  "local_number": "(416) 967-0000",
                  "e164": "+14169670000",
                  "carrier": "Bell Ontario",
                  "mode": "static",
                  "timezone": [
                    "America/Toronto"
                  ],
                  "geographical": true,
                  "verdict": "valid",
                  "reasons": [
                    "allocated fixed_line block, clean pattern"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "The number parameter is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": [
                    {
                      "loc": [
                        "query",
                        "number"
                      ],
                      "msg": "Field required",
                      "type": "missing"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "invalid or missing X-API-Key"
                }
              }
            }
          },
          "503": {
            "description": "The key check is briefly unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "key store unreachable, try again shortly"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Look up a batch",
        "operationId": "verifyBatch",
        "tags": [
          "Lookup"
        ],
        "description": "Looks up up to 10,000 numbers in one call. Results come back in the same order you sent them. Over the public URL, batches of 2,000 or fewer work best.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "numbers"
                ],
                "properties": {
                  "numbers": {
                    "type": "array",
                    "maxItems": 10000,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              },
              "example": {
                "numbers": [
                  "+14169670000",
                  "2125550123"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Results in input order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Result"
                      }
                    }
                  }
                },
                "example": {
                  "count": 1,
                  "results": [
                    {
                      "status": "success",
                      "phone": "+14169670000",
                      "phone_valid": true,
                      "phone_type": "fixed_line",
                      "phone_region": "Toronto, ON",
                      "country": "Canada",
                      "country_code": "CA",
                      "country_prefix": "1",
                      "international_number": "+1 416-967-0000",
                      "local_number": "(416) 967-0000",
                      "e164": "+14169670000",
                      "carrier": "Bell Ontario",
                      "mode": "static",
                      "timezone": [
                        "America/Toronto"
                      ],
                      "geographical": true,
                      "verdict": "valid",
                      "reasons": [
                        "allocated fixed_line block, clean pattern"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "413": {
            "description": "More than 10,000 numbers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "max 10000 numbers per batch"
                }
              }
            }
          },
          "422": {
            "description": "The body isn't {\"numbers\": [...]}.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": [
                    {
                      "loc": [
                        "body",
                        "numbers"
                      ],
                      "msg": "Field required",
                      "type": "missing"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "invalid or missing X-API-Key"
                }
              }
            }
          },
          "503": {
            "description": "The key check is briefly unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "key store unreachable, try again shortly"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/stats": {
      "get": {
        "summary": "Data coverage",
        "operationId": "stats",
        "tags": [
          "Service"
        ],
        "description": "How much numbering data the service holds and how current it is.",
        "responses": {
          "200": {
            "description": "Coverage.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "blocks": {
                      "type": "integer"
                    },
                    "area_codes": {
                      "type": "integer"
                    },
                    "by_line_type": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "data_current_to": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "blocks": 1538509,
                  "area_codes": 443,
                  "by_line_type": {
                    "voip": 736787,
                    "mobile": 566748,
                    "landline": 234965,
                    "other": 9
                  },
                  "data_current_to": "2026-09-01 00:40:05"
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "invalid or missing X-API-Key"
                }
              }
            }
          },
          "503": {
            "description": "The key check is briefly unavailable. Retry shortly.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": "key store unreachable, try again shortly"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "tags": [
          "Service"
        ],
        "security": [],
        "description": "Open, no key needed. Returns ok when the service is up.",
        "responses": {
          "200": {
            "description": "Up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "service": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "service": "mobileintelapi"
                }
              }
            }
          }
        }
      }
    }
  }
}