2.2.1 REST API Endpoints

Requests and Responses

• Our API is a REST API.
• We use json for all request and response bodies.
• Rate limit applied to all inbound requests. (Soon the detail will be provided)

HTTP Response Codes

When calling VerifySpeed endpoints and facing HTTP errors, the following HTTP response codes may be returned based on errors during request processing:

• 400: Missing or invalid input data.
  • Example: Requesting for creating verification with an inactive method.
• 401: Authentication failure.
  • Example: Missing or invalid server-key in the request.
• 403: Authorization failure.
  • Example: Attempting to access another user's data.
• 404: Resource not found.
  • Example: Using a non-existent method name.

For non-success HTTP responses (e. g., status codes outside 200-299), the response body follows the format defined by RFC 9457.

Possible Error Responses:

When provided server key is invalid server key

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Application not found",
  "status": 404,
  "errors": [
    "server-key": ["Invalid server key"]
  ]
}

When something goes wrong during verification process

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Invalid request, please contact support. (error code: VF0001)",
  "status": 400,
  "errors": []
}

Creating Phone Number Verification

Initialization

Endpoint: GET https://api.verifyspeed.com/v1/verifications/initialize

Request Headers:

• server-key: Server key obtained from the [dashboard].
• client-ipv4-address: The client’s IPv4 address.

Response (200 OK)

{
  "availableMethods": [
    {
      "methodName": "string",
      "displayName": "string"
    }
  ]
}

• availableMethods: A list of available verification methods for the client. (See Verification Methods for more details)
  • methodName: Identifier for the verification method (e.g., whatsapp-messege).
  • displayName: Display name of the method (e.g., WhatsApp Message).

---

Starting the Verification

Endpoint: GET https://api.verifyspeed.com/v1/verifications/start

Request Headers:

• server-key: Server key obtained from the [dashboard].
• client-ipv4-address: The client’s IPv4 address.

Request Body

{
  "methodName": "string",
  "language": "string"
}

• methodName: The selected verification method (required) (e.g., whatsapp-messege). (See Verification Methods for more details)
• language: The language to be used (Optional) (e.g., en).

Notes:

• The phone number must be in E.164 format (e.g. +14255552673 (1 is country code))
• Supported languages for now:
  • en for English (Default)
  • ar for Arabic
  • ckb for Central Kurdish

Response (200 OK)

{
  "methodName": "string",
  "verificationKey": "string",
  "deepLink": "string"
}

• methodName: Method name of the used verification method.
• verificationKey: The key that identifies the verification.
• deepLink (nullable): URL to complete verification by deep linking. Not null if methodName is whatsapp-messege or telegram-message.

---

Verification Result

Endpoint: GET https://api.verifyspeed.com/v1/verifications/result

Request Headers:

• server-key: Server key obtained from the [dashboard].
• token: The verification token received from the client.

Response (200 OK)

{
  "verificationMethod": "string",
  "dateOfVerification": "2024-06-24T14:51:02.877Z",
  "phoneNumber": "+12223334455"
}

• verificationMethod: The method name (e.g., whatsapp-messege) of the verification method used to verify the phone number.
• dateOfVerification: The date and time (in UTC) when the phone number was verified.
• phoneNumber: The verified phone number in E.164 format (e.g. +14255552673 (1 is country code)).