{ "openapi": "3.0.3", "servers": [ { "url": "https://api.nexmo.com/v2" } ], "security": [ { "basicAuth": [] } ], "info": { "title": "Fraud Detection", "version": "0.0.1", "description": "Fraud Detection is designed to give information which can help to identify phone numbers associated with fraud for application integrations. This API is currently in Beta.
This API will be sunset on November 23, 2025, and will no longer be available after that date.

To detect SIM Swap, please migrate to the Identity Insights API.

", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" }, "x-label": "Beta", "termsOfService": "https://www.vonage.com/legal/communications-apis/terms-of-use/", "license": { "name": "The MIT License (MIT)", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "url": "https://developer.vonage.com/number-insight/overview", "x-sha1": "081f6d985e2e4a75586da1654fde880a96885405" }, "paths": { "/ni": { "post": { "operationId": "fraud_check", "summary": "Check for Fraud", "description": "Make fraud check requests with a phone number by checking SIM swap status.\n", "requestBody": { "$ref": "#/components/requestBodies/FraudCheck" }, "responses": { "200": { "$ref": "#/components/responses/SimSwap" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "requestBodies": { "FraudCheck": { "description": "Fraud Check with SIM Swap", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheck" } } } } }, "schemas": { "FraudCheck": { "type": "object", "required": [ "type", "phone", "insights" ], "properties": { "type": { "type": "string", "description": "Accepted value is “phone” when a phone number is provided.", "enum": [ "phone" ], "example": "phone" }, "phone": { "type": "string", "description": "A single phone number that you need insight about in the [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a leading + or 00 when entering a phone number, start with the country code, e.g. 447700900000.", "example": "447009000000" }, "insights": { "type": "array", "description": "The insight you require. Must be: `sim_swap`.", "items": { "type": "string", "enum": [ "sim_swap" ] }, "example": [ "sim_swap" ] } } } }, "responses": { "SimSwap": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "type", "phone" ], "properties": { "request_id": { "type": "string", "description": "Unique UUID for this request for reference.", "example": "3f92ed75-e624-4503-abbd-a93d6b442571" }, "type": { "type": "string", "description": "The type of lookup used in the request. Currently always `phone`.", "example": "phone" }, "phone": { "type": "object", "description": "An object containing the phone number that was used in the fraud check.\n", "required": [ "phone" ], "properties": { "phone": { "description": "The phone number used in the fraud check operation(s).", "type": "string", "example": "16197363066" } } }, "sim_swap": { "type": "object", "description": "The result of the `sim_swap` insight operation. If successful, it will return `swapped: true` if the sim was swapped in the last 7 days.\n\nThe `sim_swap` object will only be returned if you specified `sim_swap` as a value in the `insights` array when the request was made.\n", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "The status of the `sim_swap` call.", "example": "completed" }, "swapped": { "type": "boolean", "description": "`true` if the sim was swapped in the last 7 days, `false` otherwise. Returned only if the sim swap check succeeds.", "example": true }, "reason": { "type": "string", "description": "The reason for a sim swap error response. Returned only if the sim swap check fails.", "example": "Mobile Network Operator Not Supported" } }, "example": { "status": "completed", "swapped": false } } } } } } }, "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "A link to the error page in our documentation", "example": "https://developer.vonage.com/api-errors" }, "title": { "type": "string", "description": "Summary of the error", "example": "Your request parameters didn't validate." }, "detail": { "type": "string", "description": "Longer description of the error", "example": "Found errors validating 1 of your submitted parameters." }, "instance": { "type": "string", "description": "Internal trace ID", "example": "a00a6d15-27db-49e7-802c-4162ebd92e61" }, "invalid_parameters": { "type": "array", "description": "Array of objects describing each individual error that was raised", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the parameter causing an error", "example": "type" }, "reason": { "type": "string", "description": "Reason why the parameter caused an error", "example": "must not be null" } } } } } } } } }, "UnauthorizedError": { "description": "Credential is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "description": "URL link to the error code reference", "example": "https://developer.vonage.com/api-errors#unauthorized" }, "title": { "type": "string", "description": "Summary of the error", "example": "Unauthorized" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "You did not provide correct credentials" }, "instance": { "type": "string", "description": "Internal trace ID", "example": "798b8f199c45014ab7b08bfe9cc1c12c" } } } } } }, "RateLimited": { "description": "Rate Limited", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Summary of the error. The error is raised when more than 5 requests per second are made.", "example": "Rate Limit Hit" }, "type": { "type": "string", "description": "URL link to the error code reference", "example": "https://developer.vonage.com/api-errors#rate-limit" }, "detail": { "type": "string", "description": "Additional information about the error", "example": "Please wait, then retry your request" }, "instance": { "type": "string", "description": "Internal trace ID", "example": "bf0ca0bf927b3b52e3cb03217e1a1ddf" } } } } } }, "InternalError": { "description": "Internal Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Summary of the error", "example": "Internal Server Error" }, "instance": { "type": "string", "description": "GUID reference for the instance", "example": "06032957-99ce-41ee-978b-9a390cd5a89b" }, "type": { "type": "string", "description": "A link to the error page in our documentation", "example": "https://developer.vonage.com/api-errors" } } } } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } } }