Report Verification Result | OTP API Reference

After EngageLab sends a verification code, if you complete verification in your own system, you can call this API to report the successful verification result for backfill statistics.

This API is free and accepts only successful verification results.

Request URL

POST https://otp.api.engagelab.cc/v1/backfill

Authentication

Please refer to Authentication to learn how to perform API authentication.

Use the API Key configured for the application that sent the message, and make sure the API Key has the verification (verify) permission.

Request Example

Request Header

POST /v1/backfill HTTP/1.1 Content-Type: application/json Authorization: Basic ${base64_auth_string}

              
              POST /v1/backfill HTTP/1.1
Content-Type: application/json
Authorization: Basic ${base64_auth_string}

This code block in the floating window

Request Body

{ "message_id": "1725407449772531712", "verified_at": 1793116800 }

              
              {
    "message_id": "1725407449772531712",
    "verified_at": 1793116800
}

This code block in the floating window

Request Parameters

The request body uses JSON. Set the request header Content-Type: application/json.

Parameter	Type	Option	Description
message_id	String	Required	Message ID of the verification code, returned by the send API
verified_at	Integer	Required	Time when verification succeeded, as a Unix timestamp in seconds

Response Parameters

Success Response

An HTTP status code of 200 means the platform has recorded this successful verification result.

Field	Type	Option	Description
code	Integer	Required	`0` on success
message	String	Required	Result description. `success` on success

{ "code": 0, "message": "success" }

              
              {
    "code": 0,
    "message": "success"
}

This code block in the floating window

Failure Response

The HTTP status code is 4xx or 5xx, and the response body contains an error code and an error description. For example, when the message has already been verified successfully, the API returns HTTP 400:

Field	Type	Option	Description
code	Integer	Required	Error code. See the error codes below
message	String	Required	Error description

{ "code": 3012, "message": "verify code has already validated" }

              
              {
    "code": 3012,
    "message": "verify code has already validated"
}

This code block in the floating window

Error Codes

Error Code	HTTP Code	Description
1000	500	Internal service error. Please try again later
2001	401	Authentication information is missing or invalid
2002	401	The API Key has expired or been disabled
2002	403	The current application is unavailable
2004	403	The API Key does not have permission to call this API
3001	400	The request JSON is invalid or a parameter type is incorrect
3002	400	A parameter value is invalid, the time is outside the allowed range, or the message does not support backfill
3012	400	The message has already been verified successfully and does not need to be reported again
4001	400	The message does not exist or does not belong to the current application

Handle errors according to code. message explains the specific reason.

Usage

Only successfully sent verification-code messages are supported. Messages that previously failed or timed out during platform verification can still be reported if you verified them successfully yourself.
The first report must be completed less than 30 days after the original message was sent. The time when the platform receives the request is used.
The successful verification time cannot be earlier than the original message send time, and cannot be later than the time when the platform receives this request.
After a message is recorded as successfully verified through this API or the Verify OTP API, further reports or verifications return 3012.

After a successful backfill, the platform pushes the corresponding message status according to the application's Callback Configuration.