{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/telesign/main/json-schema/telesign-post-score-response-schema.json",
  "title": "postScoreResponse",
  "x-generated": "2026-10-07",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/telesign-detect-api-openapi.yml#/components/schemas/postScoreResponse",
  "type": "object",
  "properties": {
    "reference_id": {
      "type": "string",
      "description": "A 32-digit hex value used to identify the web service request. The value is unique to each web service request, is randomly-generated by Telesign, and is returned in the response message immediately following the web service request."
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The customer-generated ID for this transaction that was provided in the request. If the `external_id` parameter was not included in the request, the value here is `null`."
    },
    "status": {
      "type": "object",
      "description": "An object containing details about the request status. ",
      "properties": {
        "code": {
          "type": "integer",
          "description": "One of the status codes or error codes. You should code against these and not HTTP response"
        },
        "description": {
          "type": "string",
          "description": "Text describing the transaction status."
        },
        "updated_on": {
          "type": "string",
          "description": "An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the transaction status was updated."
        }
      }
    },
    "location": {
      "$ref": "#/$defs/Location"
    },
    "numbering": {
      "$ref": "#/$defs/Numbering"
    },
    "phone_type": {
      "$ref": "#/$defs/PhoneType"
    },
    "blocklisting": {
      "$ref": "#/$defs/Blocklisting"
    },
    "carrier": {
      "$ref": "#/$defs/Carrier"
    },
    "risk": {
      "$ref": "#/$defs/Risk"
    },
    "risk_insights": {
      "$ref": "#/$defs/RiskInsights"
    }
  },
  "$defs": {
    "Blocklisting": {
      "title": "Blocklisting",
      "type": "object",
      "description": "Contains details about whether the number was blocked and who requested the block. Contact our [Customer Support Team](mailto:support@telesign.com) to include this package in your response.\n",
      "properties": {
        "block_code": {
          "type": "integer",
          "description": "A code indicating whether the number is blocked, and who blocked it. `0` for not blocked, `1` for blocked by TeleSign, `2` for block requested by your organization, `3` for block requested by your account or set by TeleSign on behalf of your account, and `4` if the block state is unknown."
        },
        "block_description": {
          "type": "string",
          "description": "Text explaining the block status."
        },
        "blocked": {
          "type": "boolean",
          "description": "If `true`, this number is blocked. If `false`, this number is not blocked."
        }
      }
    },
    "Carrier": {
      "title": "Carrier",
      "type": "object",
      "description": "Contains details about the company that provides telecommunications services for this phone number. Behavior of this property, including information returned for ported phone numbers, can vary depending on the country of the phone number. See [How does carrier data vary by country?](https://support.telesign.com/s/article/How-does-carrier-data-vary-by-country) for more details.",
      "properties": {
        "carrier_id": {
          "type": "integer",
          "description": "An ID specifying this carrier. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response."
        },
        "name": {
          "type": "string",
          "description": "The name of this carrier."
        }
      }
    },
    "Location": {
      "title": "Location",
      "type": "object",
      "description": "Contains geographical location information associated with the rate center of the phone number when the device was activated. Null is returned when data for a field isn't available for a specific market or country.",
      "properties": {
        "city": {
          "type": "string",
          "description": "The city associated with the rate center of the phone number when the device was activated."
        },
        "county": {
          "type": "string",
          "description": "The county (or parish) associated with the rate center of the phone number when the device was activated (U.S. only)."
        },
        "state": {
          "type": "string",
          "description": "The two-letter [state abbreviation code](http://pe.usps.com/text/pub28/28apb.htm) of the state (province, district, or territory) associated with the rate center of the phone number when the device was activated (North America only)."
        },
        "zip": {
          "type": "string",
          "description": "The five-digit United States Postal Service [ZIP Code](https://www.usps.com/nationalpremieraccounts/findzipcodes.htm) associated with the rate center of the phone number when the device was activated (U.S. only)."
        },
        "country": {
          "type": "object",
          "description": "Contains properties related to the country associated with the rate center of the phone number when the device was activated.",
          "properties": {
            "iso2": {
              "type": "string",
              "description": "The ISO 3166-1 2-letter [country code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated."
            },
            "iso3": {
              "type": "string",
              "description": " The ISO 3166-1 3-letter country code associated with the rate center of the phone number when the device was activated."
            },
            "name": {
              "type": "string",
              "description": "The [country name](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated."
            }
          }
        },
        "time_zone": {
          "type": "object",
          "description": "Contains properties related to the time zone associated with the rate center of the phone number when the device was activated. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.",
          "properties": {
            "name": {
              "type": "string",
              "description": "The time zone associated with the rate center of the phone number when the device was activated (U.S. only)."
            },
            "utc_offset_max": {
              "type": "string",
              "description": " For international phone numbers, this parameter returns the maximum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the same result as utc_offset_min."
            },
            "utc_offset_min": {
              "type": "string",
              "description": "For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the UTC offset associated with the rate center of the phone number when the device was activated. "
            }
          }
        },
        "coordinates": {
          "type": "object",
          "description": "Contains properties with details about the geographical coordinates of the location where the phone number is registered.",
          "properties": {
            "latitude": {
              "type": "number",
              "description": "Latitude specifies the North-South position of a point on the Earth’s surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole). It is returned here as a value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places.",
              "format": "float"
            },
            "longitude": {
              "type": "number",
              "description": "Longitude specifies the East-West position of a point on the Earth’s surface. It is an angle measured East or West from the [prime meridian](https://en.wikipedia.org/wiki/Prime_meridian) —ranging from 0° at the prime meridian, to +180° Eastward and -180° Westward. It is returned here as a value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places.",
              "format": "float"
            }
          }
        },
        "metro_code": {
          "type": "string",
          "description": "A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the rate center of the phone number when the device was activated (U.S. only). PMSA Codes are governed by the [US Census Bureau](http://www.census.gov/). This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480."
        }
      }
    },
    "Numbering": {
      "title": "Numbering",
      "type": "object",
      "description": "Contains properties related to the numbering attributes of the specified phone number.",
      "properties": {
        "original": {
          "type": "object",
          "description": "Contains details about the original phone number included in the request.",
          "properties": {
            "phone_number": {
              "type": "string",
              "description": "The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes)."
            },
            "complete_phone_number": {
              "type": "string",
              "description": "The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes)."
            },
            "country_code": {
              "type": "string",
              "description": "The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`."
            }
          }
        },
        "cleansing": {
          "type": "object",
          "description": "Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.",
          "properties": {
            "call": {
              "type": "object",
              "description": "Contains cleansing details for the phone number if it is enabled to receive voice calls.",
              "properties": {
                "cleansed_code": {
                  "type": "integer",
                  "description": "One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number."
                },
                "country_code": {
                  "type": "string",
                  "description": "The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`."
                },
                "max_length": {
                  "type": "integer",
                  "description": "The maximum number of digits allowed for phone numbers with this country dialing code."
                },
                "min_length": {
                  "type": "integer",
                  "description": "The minimum number of digits allowed for phone numbers with this country dialing code."
                },
                "phone_number": {
                  "type": "string",
                  "description": "The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes)."
                }
              }
            },
            "sms": {
              "type": "object",
              "description": "Contains cleansing details for the phone number if it is enabled to receive SMS.",
              "properties": {
                "cleansed_code": {
                  "type": "integer",
                  "description": "One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number."
                },
                "country_code": {
                  "type": "string",
                  "description": "The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`."
                },
                "max_length": {
                  "type": "integer",
                  "description": "The maximum number of digits allowed for phone numbers with this country dialing code."
                },
                "min_length": {
                  "type": "integer",
                  "description": "The minimum number of digits allowed for phone numbers with this country dialing code."
                },
                "phone_number": {
                  "type": "string",
                  "description": "The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes)."
                }
              }
            }
          }
        }
      }
    },
    "PhoneType": {
      "title": "PhoneType",
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes)."
        },
        "override_reason": {
          "type": "string",
          "description": "Text describing the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response."
        },
        "description": {
          "type": "string",
          "description": "Text describing the phone type."
        },
        "override_reason_id": {
          "type": "integer",
          "description": "A numeric code specifying the [phone type override](/enterprise/docs/codes-languages-and-time-zones#phone-type-override-reason-codes) status of this phone number. Contact our [Customer Support Team](mailto:support@telesign.com) to include this property in your response."
        }
      }
    },
    "Risk": {
      "title": "Risk",
      "type": "object",
      "description": "Contains properties related to the risk recommendation for the specified phone number.",
      "properties": {
        "level": {
          "type": "string",
          "description": "The severity of the risk. [Risk Recommendation Scales](/enterprise/docs/intelligence-get-started#risk-recommendation-scales) provides a table."
        },
        "recommendation": {
          "type": "string",
          "enum": [
            "allow",
            "flag",
            "block"
          ],
          "description": "The action that Telesign recommends that you take based on the risk recommendation."
        },
        "score": {
          "type": "integer",
          "description": "A measure of the transaction risk involved with conducting an online business transaction at the current time for this phone number. The scale ranges from zero to 1000, with a higher value indicating a higher risk."
        }
      }
    },
    "RiskInsights": {
      "title": "RiskInsights",
      "type": "object",
      "description": "Contains reason code properties with additional info related to the risk recommendation.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of these reason codes.",
      "properties": {
        "status": {
          "type": "integer",
          "description": "The processing status of the risk insights package for this request.\n\nPossible values are:\n\n| Value | Meaning |\n|-------|---------|\n| 800   | **Success.**<br /> All fields successfully returned and available for use. |             \n| 801   | **Partial Success.**<br /> No value available for category, but other data is available. | \n| 803   | **Error.**<br /> An error occurred; no data returned in this response. | \n\n",
          "enum": [
            800,
            801,
            803
          ]
        },
        "category": {
          "type": "array",
          "description": "Reason codes related to the category of the phone number.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        },
        "a2p": {
          "type": "array",
          "description": "Reason codes specific to application-to-person communication (A2P). These are automated communications sent to a human, like verification codes, appointment reminders, etc.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        },
        "p2p": {
          "type": "array",
          "description": "Reason codes specific to person-to-person communication (P2P). This is two-way communication between two humans, like one friend texting another.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        },
        "number_type": {
          "type": "array",
          "description": "Reason codes related to the phone number’s type.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        },
        "ip": {
          "type": "array",
          "description": "Reason codes related to activity of the IP you provided for this phone number.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        },
        "email": {
          "type": "array",
          "description": "Reason codes related to activity of the email address you provided for this phone number.\n <br />*[Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings)* provides the meaning of the codes returned.",
          "items": {
            "type": "integer"
          }
        }
      }
    }
  }
}