---
updatedAt: 2026-09-24T13:53:07.000Z
---

# /call-protection/v2/

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "Protect+ API",
    "version": "1.1",
    "termsOfService": "https://firstorion.com/terms-use/",
    "contact": {
      "name": "First Orion"
    },
    "description": "**Protect+** is a lightweight REST based API that can easily\nintegrate with a network element and provide feedback on a call-by-call basis.\n\nBy providing the calling number in the API POST request, the\nAPI response can provide the associated Risk Level,\nand Category.  Through the client’s own local policies,\nthis information in the API response can be leveraged to take\nactionable steps such as warning the called party of a scam\ncall or providing call purpose for a low-risk legitimate\nbusiness such as Charity, or even blocking the call outright.\n\nThe architecture of Protect+, and all of First Orion’s\nreal-time call protection services, allows for continuous\ndata and analytics updates. The continuous availability of\nnew data provided to the protection services also allows\nfor low latency, which is critical for any real-time\nprotection solution.\n\n### How to use the APIs\n\n#### Basic request flow\n\n1. Acquire an auth token by sending a `POST` request using the api key\nand api secret First Orion has provided to you.\n2. Use the token as an Authorization header as you submit\nrequests to various API endpoints.\n3. When the auth token expires you must acquire a new token\nusing the `refresh_token` received as part of step #1.\nThis is done by submitting a `POST` request to the\n`refresh` endpoint of the Auth service.\n"
  },
  "servers": [
    {
      "url": "https://api.firstorion.com",
      "description": "Production environment"
    },
    {
      "url": "https://api.forp-lab.com",
      "description": "Lab environment for customer integration"
    }
  ],
  "tags": [
    {
      "name": "Protect+"
    }
  ],
  "components": {
    "schemas": {
      "ErrorWrapper": {
        "type": "object",
        "example": {
          "code": 400,
          "message": "invalid number format"
        },
        "properties": {
          "code": {
            "type": "number",
            "description": "An code identifying the type of error",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "A string explanation of the error",
            "example": "invalid number format"
          }
        }
      },
      "ProtectPlusV2ResponseBody": {
        "type": "object",
        "properties": {
          "aNumber": {
            "type": "string",
            "example": "+15017685432",
            "description": "E.164 calling party phone number that was queried"
          },
          "riskLevel": {
            "type": "string",
            "description": "Risk level associated with this calling number",
            "enum": [
              "LOW",
              "MEDIUM",
              "HIGH"
            ],
            "example": "HIGH"
          },
          "category": {
            "type": "string",
            "description": "Category of the calling party",
            "example": "SCAM",
            "enum": [
              "",
              "NUISANCE",
              "SCAM",
              "CUSTOMER_SERVICE",
              "DEBT_COLLECTION",
              "INFORMATIONAL",
              "CHARITY",
              "POLITICAL",
              "SURVEY",
              "TELEMARKETING",
              "PRISON"
            ]
          },
          "callTime": {
            "type": "integer",
            "example": 1699999414,
            "description": "Unix epoch timestamp (in seconds) when the call was approximately initiated"
          },
          "bNumber": {
            "type": "string",
            "example": "+18702500123",
            "description": "E.164 recipient phone number being called"
          },
          "verstat": {
            "type": "string",
            "example": "No-TN-Validation",
            "enum": [
              "No-TN-Validation",
              "TN-Validation-Passed",
              "TN-Validation-Failed"
            ]
          }
        }
      },
      "ProtectPlusV2RequestBody": {
        "type": "object",
        "required": [
          "aNumber"
        ],
        "example": {
          "aNumber": "+15017685432",
          "bNumber": "+18702500123",
          "callTime": 1699999414,
          "verstat": "No-TN-Validation"
        },
        "properties": {
          "aNumber": {
            "type": "string",
            "example": "+15017685432",
            "description": "E.164 calling party phone number"
          },
          "bNumber": {
            "type": "string",
            "example": "+18702500123",
            "description": "E.164 recipient phone number being called"
          },
          "callTime": {
            "type": "integer",
            "example": 1699999414,
            "description": "Unix epoch timestamp (in seconds) when the call was approximately initiated"
          },
          "verstat": {
            "type": "string",
            "example": "No-TN-Validation",
            "enum": [
              "No-TN-Validation",
              "TN-Validation-Passed",
              "TN-Validation-Failed"
            ]
          }
        }
      }
    },
    "responses": {
      "ProtectPlusV2Response": {
        "description": "",
        "headers": {
          "x-forp-meta-request-id": {
            "description": "UUID generated by First Orion for request correlation purposes. You may also use this value for your own tracing.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "f731287d-ac62-4c54-8434-ac7c3f593b34"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "example": {
                "body": {
                  "aNumber": "+15017685432",
                  "riskLevel": "HIGH",
                  "category": "SCAM",
                  "bNumber": "+18702500123",
                  "callTime": 1699999414,
                  "verstat": "No-TN-Validation"
                },
                "error": null
              },
              "properties": {
                "body": {
                  "$ref": "#/components/schemas/ProtectPlusV2ResponseBody"
                },
                "error": {
                  "$ref": "#/components/schemas/ErrorWrapper"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "paths": {
    "/call-protection/v2/": {
      "post": {
        "tags": [
          "Protect+"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProtectPlusV2RequestBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/ProtectPlusV2Response"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": true
  }
}
```