Public Verify API

Your access token:

{yourToken}

This access token belongs to your user {userId}.

In order to authenticate your request you need to pass it in request's header Authorization. The value must be prefixed with the Bearer string:

Authorization: Bearer {yourToken}

The token is issued for the verification_service_user role, so it can be used only for the two endpoints described below. Any other OnPhone API endpoint will answer with a 403 status code for this token.

In case of a missing, malformed or expired token you will receive a response with 401 status code:

{
  "name": "Unauthorized",
  "message": "Your request was made with invalid credentials.",
  "code": 0,
  "status": 401
}

Sending a verification

In order to send a verification code, perform the next request. The request body might be sent as a application/x-www-form-urlencoded, application/json or multipart/form-data serialized string. In the example below JSON body is used.

curl -X POST \
     -H 'Authorization: Bearer {yourToken}' \
     -H 'Content-Type: application/json' \
     -d '{"phoneNumber": "+16468512286"}' \
     https://onphone.app/api/services/verifications/send

The request body fields:

The supported channels are telegram and sms. When more than one channel is allowed, they are tried in the following order: telegram, then sms. The first channel which accepts the code for delivery is used, and the channel that was actually used is returned in the response. Availability of the channels depends on the destination country, so a country can be served by sms while not being served by telegram.

To restrict the delivery to a single channel, pass it explicitly:

curl -X POST \
     -H 'Authorization: Bearer {yourToken}' \
     -H 'Content-Type: application/json' \
     -d '{"phoneNumber": "+16468512286", "channels": ["sms"]}' \
     https://onphone.app/api/services/verifications/send

In case of successful submit you will receive a response with 200 status and JSON content of the sent verification:

{
  "id": 1,
  "phoneNumber": "+16468512286",
  "codeLength": 6,
  "codeDictionary": "digits",
  "channel": "sms",
  "sentAt": 1772375695
}

Verification object schema:

{
  "id": "integer",
  "phoneNumber": "string",
  "codeLength": "integer",
  "codeDictionary": "string",
  "channel": "string",
  "sentAt": "integer"
}

The codeDictionary field describes the alphabet of the sent code and can have the following values: digits, letters, mixed. The channel field can have the following values: sms, telegram. The sentAt field is a unix timestamp. The code is valid for 5 minutes since sentAt.

You need to take the id field from the response: it is required to verify the code entered by the user.

In case of an error you will receive a response with 400 status code and JSON content with the errors array, where every item describes a single error with a machine readable code and a human readable message:

{
  "errors": [
    {
      "code": "OUT_OF_BALANCE",
      "message": "There is not enough credits on your account to perform this action"
    }
  ]
}

The expected error codes of this request are:

Verifying the code

In order to check the code entered by the user, perform the next request. Take a note that there is an {id} param in URL, which must be replaced to the corresponding verification id received from the send request:

curl -X POST \
     -H 'Authorization: Bearer {yourToken}' \
     -H 'Content-Type: application/json' \
     -d '{"code": "123456"}' \
     https://onphone.app/api/services/verifications/{id}/verify

In case of successful check you will receive a response with 200 status and the result of the check:

{
  "isValid": true
}

The isValid: false value means that the passed code does not match the sent one. The verification is not closed in this case, so the user may be asked to retype the code until the verification expires. Once isValid: true has been returned, the verification is closed and cannot be reused.

In case of an error you will receive a response with 400 status code and the same errors array as described above. The expected error codes of this request are:

If the passed {id} does not exist, you will receive a response with 404 status code:

{
  "name": "Not Found",
  "message": "",
  "code": 0,
  "status": 404
}

Billing

Every sent verification is charged in credits from your account balance. The amount depends on the used channel and the destination country, and it is known only after the code has been submitted.

The send request is rejected with the OUT_OF_BALANCE error code when your balance is already negative, so keeping a positive balance is enough to be able to send verifications.