> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greip.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phone Scoring
> This method serves as an additional layer of protection in your system for validating phone numbers. It not only checks the syntax but also assesses the likelihood of the phone number being valid and operational.
By incorporating this scoring into your workflow, you can enhance fraud detection, reduce invalid inputs, and improve the overall quality of data captured.
export const MCPCallout = () => {
return
;
};
## Authentication
Include your API key in the `Authorization` header:
```http theme={null}
Authorization: Bearer
```
API v2 accepts the key only in this header, not in query parameters or request bodies. See [Authentication](/authentication).
### Path parameters
The phone number you want to validate.
Expected values: a phone number
Sample value: `+12121234567`, `0012121234567`, `12121234567`, or `2121234567`
### Query parameters
The `ISO 3166-1 alpha-2` format of the country code of the phone number. [Learn more](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
Sample value: `US`
The format command is used to get a response in a specific format.
Expected values: `JSON`, `XML`, `CSV`, or `Newline`
For more information please refer to [Response format](/options/response-format).
The mode command is used in the development stage to simulate the integration process before releasing it to the production environment.
Expected values: `live`, or `test`.
For more information please refer to [Development environment](/options/development-environment).
Optional label for your own analytics or support correlation (for example a product or channel name).
The user\_id command can be used to identify requests sent by specific users to monitor in the [Events page](/knowledge-base/events-and-alerts/overview).
Expected values: email address, phone number, user id, name, etc.
For more information please refer to [User identifier](/options/user-identifier).
```json Success theme={null}
{
"success": true,
"data": {
"carrier": null,
"is_valid": false,
"is_blacklisted": false,
"is_disposable": false,
"phone": "+12121234567",
"country_code": "US",
"risk_level": "high",
"recommendation": "reject",
"reasons": ["Invalid phone number structure."],
"custom_rules_applied": {
"total": 0,
"rules": []
}
},
"execution_ms": 1
}
```
```json Error theme={null}
{
"success": false,
"code": 101,
"type": "invalid_key",
"description": "The API Key is missing or invalid."
}
```
### Response properties
`true` when the request succeeded; `false` on error.
Carrier name of the phone number.
Overall risk band (`low`, `medium`, or `high`).
Suggested action (`accept`, `review`, or `reject`).
Human-readable strings explaining elevated risk. Empty when `risk_level` is `low`.
Whether the number passes structure and validation checks for the given `country_code`.
Indicates if the phone number is blacklisted due to applying [custom
rules](/knowledge-base/custom-rules/overview) or were found in one of your
blacklists.
Whether the number is flagged as disposable or spam.
The phone number you sent in the request.
The country code you sent in the request (ISO 3166-1 alpha-2).
The custom rules applied to this request, [learn
more](/knowledge-base/custom-rules/overview).
The total number of custom rules applied to this request.
The custom rules applied to this request, [learn
more](/knowledge-base/custom-rules/overview).
The rule ID as shown in the dashboard (e.g: `CR104`).
The rule title you set when creating the rule.
Time taken to process the request (milliseconds).
## OpenAPI
````yaml openapi/v2.json GET /score/phone/{phone}
openapi: 3.0.3
info:
title: Greip API v2 (docs playground)
version: 2.0.0
servers:
- url: https://v2.greipapi.com
security: []
paths:
/score/phone/{phone}:
get:
summary: Phone scoring
operationId: scorePhone
parameters:
- name: phone
in: path
required: true
schema:
type: string
- name: country_code
in: query
required: true
schema:
type: string
- name: format
in: query
schema:
type: string
default: JSON
- name: mode
in: query
schema:
type: string
default: live
- name: source
in: query
schema:
type: string
- name: user_id
in: query
schema:
type: string
responses:
'200':
description: OK
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.