{"openapi":"3.0.0","info":{"title":"SMS Verify API","version":"1.0","description":"Use the Telesign SMS Verify API to send an SMS with a one-time passcode (OTP) to a recipient phone number.","contact":{"name":"Telesign Customer Support Team","email":"support@telesign.com"}},"servers":[{"url":"https://rest-ww.telesign.com"}],"paths":{"/v1/verify/sms":{"parameters":[],"post":{"summary":"Send SMS verification code","responses":{"200":{"$ref":"#/components/responses/200Response"},"400":{"$ref":"#/components/responses/400Response"},"401":{"description":"**Unauthorized.** The request requires user authentication. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Status code | Status description   | Error code | Description   |\n|------------|--------------------------|------------|--------------------------|\n| 500 | Transaction not attempted | -10009     | Invalid source IP address |\n| 500 | Transaction not attempted | -10033     | {phone_number} has not been verified for this trial account. |\n| 501 | Not authorized            | -20002     | This product is not enabled for this Customer ID.  |\n| 501 | Not authorized            | -30000     | Invalid Customer ID. |\n| 501 | Not authorized            | -30001     | Customer ID Account Suspended. |\n| 501 | Not authorized            | -30004     | Missing required 'Authorization' header |\n| 501 | Not authorized            | -30005     | Required 'Authorization' header is not in the correct format|\n| 501 | Not authorized            | -30006     | Invalid Signature |\n| 501 | Not authorized            | -30007     | Missing required 'Date' or 'x-ts-date' header    |\n| 500 | Transaction not attempted | -30008     | Invalid 'x-ts-auth-method' header.|\n| 501 | Not authorized            | -30009     | 'Date' or 'x-ts-date' header is not RFC822 compliant  |\n| 501 | Not authorized            | -30010     | 'Date' or 'x-ts-date' header is not within tolerable range |\n| 501 | Not authorized            | -30011     | 'x-ts-nonce' header value is either too long or too short |\n| 501 | Not authorized            | -30012     | 'x-ts-nonce' header value has been used recently |\n| 501 | Not authorized            | -30015     | Invalid API Key.  |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/401ResponseSchema"},{"type":"object","properties":{"signature_string":{"type":"string","description":"Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.","example":"POST\\napplication/x-www-form-urlencoded\\n\\nx-ts-auth-method: HMAC-SHA256\\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\\nx-ts-nonce:ab$CDef/gh123+II4jk\\nphone_number=11234567890\\n/v1/verify/sms"}}}]},"examples":{"Unauthorized":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[{"code":-10009,"description":"Invalid source IP address"}],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":500,"description":"Transaction not attempted"}}}}}}},"429":{"$ref":"#/components/responses/429Response"},"500":{"$ref":"#/components/responses/500Response"}},"x-readme":{"code-samples":[{"name":"C#","language":"csharp","code":"using RestSharp;\n\nvar client = new RestClient(\"https://rest-ww.telesign.com/v1/messaging\");\nvar request = new RestRequest(\"POST\");\n\nrequest.AddHeader(\"accept\", \"application/json\");\nrequest.AddHeader(\"content-type\", \"application/x-www-form-urlencoded\");\nrequest.AddHeader(\"authorization\", \"Basic [REDACTED]\");\nrequest.AddParameter(\"application/x-www-form-urlencoded\", \"is_primary=true&phone_number=8184823381&message=hello&message_type=ARN&account_lifecycle_event=1&external_id=88888\", ParameterType.RequestBody);\n\nRestResponse response = client.Execute(request);"}]},"operationId":"sendSMSVerifyCode","description":"Use this action to send an SMS with a verification code to a recipient phone number.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) (easiest to implement) or [Digest](/enterprise/docs/authentication#digest-authentication)\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Accepts:** `application/x-www-form-urlencoded`\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/x-www-form-urlencoded`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)\n","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","description":"The end user's phone number you want to send a message to, as digits without spaces or special characters, beginning with the country dialing code.","example":"15558675309"},"ucid":{"type":"string","description":"A code specifying the use case you are making the request for. Choices include:\n* `ATCK` - For use in a 2FA situation like updating an account or logging in.\n* `BACF` - For creating an account where the service may be vulnerable to bulk attacks and fraudsters.\n* `BACS` - For creating an account where the service may be vulnerable to bulk attacks or individual spammers.\n* `CHBK` - For use when someone is trying to buy something expensive or unusual and you want to verify it is really them.\n* `CLDR` - Calendar event.\n* `LEAD` - For use in a situation where you require a person to enter personal details to request information about a potential purchase (like a loan, real estate, or attending a school), and you want to check if they are legitimate.\n* `OTHR` - For a situation not addressed by other tags.\n* `PWRT` - For use in a situation where a password reset is required.\n* `RESV` - For use when you have end users making reservations, and you want to confirm they will show up.\n* `RXPF` - For use when you are trying to prevent prescription fraud.\n* `SHIP` - For use when you are sending a shipping notification.\n* `THEF` - For use when you are trying to prevent an end user from deactivating or redirecting a phone number for identity theft purposes.\n* `TRVF` - For use when you are transferring money and want to check if the transfer is approved by sending a text message to your end user. This is similar to `CHBK`, but is specifically for a money transaction.\n* `UNKN` - For a situation not addressed by other tags (same as `OTHR`)."},"originating_ip":{"type":"string","description":"Your end user's IP address (do not send your own IP address). This is used to help Telesign improve our services. IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled <a href=\"https://tools.ietf.org/html/rfc791\">Internet Protocol</a>. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled <a href=\"https://tools.ietf.org/html/rfc4291#section-2.2\">IP Version 6 Addressing Architecture</a>."},"language":{"type":"string","description":"A code specifying the language of the predefined template you wish to use. For a complete list of codes, see [SMS Verify API - Supported languages](/enterprise/docs/sms-verify-api-supported-languages). If you provide overriding message text in the `template` parameter, this field is not used."},"verify_code":{"type":"string","description":"The verification code used for the code challenge. By defauls, Telesign randomly generates a seven-digit numeric value for you. You can override the default behavior by including your own numeric code for this parameter, with a value between `000` and `9999999`. Only numeric characters are supported. Either way, the verification code replaces the variable `$$CODE$$` in the message template. ","example":"57244","minLength":3,"maxLength":7},"template":{"type":"string","description":"Text that overrides the contents of the predefined message templates. Include the `$$CODE$$` variable to have the verification code automatically inserted. For payment transactions, include the `$$AMOUNT$$` and `$$PAYEE$$` variables to have those payment details from your other params automatically inserted. By default, the maximum length of this field is 160 characters. Telesign recommends that you keep your messages brief if possible, but if you want to send longer messages contact our Customer Support Team to have the maximum increased. A long message may be up to 1600 characters.","example":"Your code is $$CODE$$"},"sender_id":{"type":"string","description":"Specifies the sender ID to be displayed to the end user on the SMS message. Before using this, give any sender IDs you might want to use to our Customer Support Team, so we can add them to our allow list. If the sender ID in this field is not on this list, it is not used. We do not guarantee that the sender ID you specify will be used; Telesign may override this value to improve delivery quality or to follow the SMS regulations of particular countries. We recommend limiting values to 0-9 and A-Z, as support for other ASCII characters varies by carrier.","maxLength":20},"is_primary":{"type":"string","description":"Whether you are using this service as your primary provider to send this message (`”true”`) or\"as a backup after your primary provider failed (`”false”`). We use this data to optimize message routing.","default":"true"},"dlt_template_id":{"type":"string","maxLength":40,"description":"**(India-local traffic only)**. The ID of the DLT template used for this message. See [India DLT Update](https://support.telesign.com/s/article/India-DLT-Update) for more details on the relevant regulations."},"dlt_entity_id":{"type":"string","maxLength":40,"description":"**(India-local traffic only)**. The ID of the entity sending this message. See [India DLT Update](https://support.telesign.com/s/article/India-DLT-Update) for more details on the relevant regulations."},"transaction_amount":{"type":"string","description":"**(Payment-transactions only)**  Replaces the `$$AMOUNT$$` variable in the message template. Specifies the currency and amount for the payment that the end user is approving. This parameter is required if `transaction_payee` is included in the request.","maxLength":40},"transaction_payee":{"type":"string","description":"**(Payment-transactions only)** Replaces the `$$PAYEE$$` variable in the message template. Specifies the entity that the end user is approving a payment to.\nThis parameter is required if `transaction_amount` is included in the request.","maxLength":40},"sim_swap_check":{"type":"string","description":"Set a value of `\"true\"` to screen this transaction using a Telesign SIM Swap check. This only has an effect if we have enabled SIM Swap for your account and configured it to be toggled using this parameter. If your account is configured to perform the check on every transaction, set a value of `\"false\"` to suppress the check. Contact our [Customer Support Team](mailto:support@telesign.com) to turn on this feature.","maxLength":40},"callback_url":{"type":"string","description":"A URL where you want delivery reports to be sent related to your request. This overrides any default callback URL that you’ve previously set. The override only lasts for this request."}},"required":["phone_number"]}}}},"tags":["Messages"]}},"/v1/verify/{reference_id}":{"parameters":[{"schema":{"type":"string"},"name":"reference_id","in":"path","required":true}],"get":{"summary":"Get transaction status","responses":{"200":{"description":"Success. Your request was fulfilled and resulted in data being retrieved. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n | Status code | Associated text string | Description                                      |\n |-------------|------------------------|--------------------------------------------------|\n | 200         | Delivered to handset   | The SMS was delivered to the end user's phone. (Final)   |\n | 201         | Transaction successfully completed, suspicious activity detected   | Telesign's internal anti-fraud mechanisms identified potentially suspicious activity related to the destination phone number.   |\n | 203         | Delivered to gateway   | The SMS was delivered to the gateway. If the gateway responds with further information (including successful delivery to handset or delivery failure), the status is updated.    (Intermediate)  |\n | 207         | Error delivering SMS to handset (reason unknown)  | The SMS could not be delivered to the end user's handset for an unknown reason. (Final) |\n | 210         | Temporary phone error  | The SMS could not be delivered to the handset due to a temporary error with the phone. Examples - phone is turned off, not enough memory to store the message. (Final)   |\n | 211         | Permanent phone error  | The SMS could not be delivered to the handset due to a permanent error with the phone. For example, the phone is incompatible with SMS, or illegally registered on the network. This can happen when a phone number is blacklisted, or is incorrectly provisioned. (Final)    |\n | 220         | Gateway/network cannot route message | The network cannot route the message to the handset. (Final)   |\n | 221         | Message expired before delivery | The message was queued by the mobile provider and timed out before it could be delivered to the handset. (Final)  |\n | 222         | SMS not supported      | SMS is not supported by this phone, carrier, plan, or user.  |\n | 229         | Message blocked by customer request  | Telesign blocked the SMS before it was sent. This is due to your prior submitted request to blocklist this phone number. |\n | 230         | Message blocked by Telesign    | Telesign blocks a message if it is being sent to a phone number that is on a global blocklist.    |\n | 231         | Invalid/unsupported    | Invalid/unsupported message content.      |\n | 233         | Message blocked due to high risk score. | It was determined that the risk score for the destination number is higher than configured Maximum Risk Score. For that reason Telesign did not send the SMS.  |\n | 237         | Message blocked in requested country|You requested that messages in a specific country be blocked, and the message was being sent to this country.|\n | 250         | Final status unknown   | The final status of the SMS cannot be determined.|\n | 251         | Message successfully sent out for delivery, however final confirmation of delivery to handset was not received. | Telesign successfully delivered the message through our gateway and it passed downstream. However, Telesign did not receive a delivery receipt within 12 hours of transmission. We cannot confirm delivery to the handset. The end user most likely did not receive the message. |\n | 290         | Message in progress    | The message is being sent to the SMS gateway.    |\n | 292         | Queued by gateway      | The SMS gateway has queued the message.          |\n | 295         | Status delayed         | The status of the SMS is temporarily unavailable.|\n | 500         | Transaction not attempted   | No SMS request was attempted. |\n | 501         | Not authorized         | No permissions for this resource, or authorization failed.                            |\n | 502         | Campaign error         | This error can be generated if there is a problem with the short code used.                        |\n | 503         | Carrier rejected - temporary problem | This error is generated if there is an error on the carrier or operator side that is temporary and the message can be retried.      |\n | 504         | Carrier rejected - permanent error | This error is generated if there is an error on the carrier or operator side that is permanent and the message should not be retried.      |\n | 505         | Error on gateway - temporary error | This error is generated if there is an error on Telesign's partner side that is considered temporary and the message can be retried.      |\n | 506         | Error on gateway - permanent error    | This error is generated if there is an error on Telesign's partner side that is considered permanent and the message should not be retried. |\n | 507         | Invalid destination address   | There is a problem with the destination address used. Either the format is not valid, or the number is not associated with any carrier, or if MSC is used it does not know about this MSISDN.  |\n | 508         | Invalid source address | The message requires a source address. Verify that one is provided and correct.   |\n | 509         | Parameters problem     | One or more parameters used in the request is not supported.   |\n | 510         | Message blocked by subscriber action or  request   | The end user has blocked receiving SMS with their carrier plan or by request or from the particular short code used.  |\n | 511         | Subscriber low on credit     | The end user exceeded their spending limits and cannot receive SMS.   |\n | 512         | Roaming error          | End user cannot receive SMS because their device that receives the messages is roaming.  |\n | 513         | Mobile number portability error  | SMS failed because ported combinations are unreachable. |\n | 514         | Subscriber absent      | The operator/carrier is temporarily unable to reach the end user.   |\n | 515         | Suspected spam         | This message is considered to be spam by carrier or operator.    |\n | 517         | Selected DLT details for India not supported|The DLT template ID or entity ID in the request cannot be found by the end operator.|\n | 518         | Message blocked due to high risk SIM SWAP indicator|The service determined that the SIM swap risk indicator for the destination number is higher than the maximum value configured for your account. For that reason Telesign did not send the SMS. |\n | 519         | Message not sent - requested SIM SWAP check could not be performed|The service could not perform the SIM swap check. This is because either the number is out of SIM swap coverage or information about the potential SIM swap event is missing. |\n | 520 | Content sent is not allowed|The content in this message is not permitted by the carrier. |\n | 521         | Requested Sender ID is not allowed for destination |The sender ID submitted in request is not allowed in destination country/operator. |\n | 599         | Status not available | The system is unable to provide status at this time.  |\n\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/getStatusResponse"},{"type":"object","properties":{"sim_swap":{"$ref":"#/components/schemas/SIMSwapResponse"}}}]},"examples":{"Success":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[],"status":{"description":"Delivered to handset","updated_on":"2022-31-03T14:51:28.709526Z","code":200},"verify":{"code_state":"VALID","code_entered":"45558"},"additional_info":{"message_part_sequence_number":1,"message_parts_count":1,"message_parts_reference_ids":"35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12"}}},"SIM Swap enabled":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[],"status":{"code":518,"description":"Message blocked due to high risk SIM SWAP indicator","updated_on":"2022-31-03T14:51:28.709526Z"},"verify":{"code_state":"UNKNOWN","code_entered":""},"sim_swap":{"risk_indicator":4,"swap_time":"15:44:31","status":{"code":2800,"description":"Request successfully completed"},"swap_date":"2022-30-03"}}}}}}},"400":{"description":"Bad request. The request could not be understood by the server due to malformed syntax. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Error Code | Associated text string   |\n|------------|--------------------------|\n| -10001     | Invalid Request: ReferenceID Parameter: <reference_id> |\n| -10001     | Invalid Request: CustomerID Parameter: <customer_id>   |\n| -10001     | Invalid Request: AuthenticationID                      |\n| -10001     | Invalid Request: CustomerID/AuthenticationID Parameter: <customer_id>/<authentication_id> |\n| -10001     | Invalid Request: customer_id Parameter: <customer_id> |\n\nAssociated text string for -10001 will change depending on the parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getStatusResponse"},"examples":{"Invalid Request":{"value":{"reference_id":"None","sub_resource":"","errors":[{"code":-10001,"description":"Invalid Request: ReferenceID Parameter: None"}],"status":{"code":500,"description":"Transaction not attempted","updated_on":"2022-31-03T14:51:28.709526Z"}}}}}}},"401":{"description":"Unauthorized. The request requires user authentication. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Error Code | Associated text string   |\n|------------|--------------------------|\n| -10001     | Not Allowed Host: Hostname Parameter: \\<parameter> |\n| -10001     | Not Allowed Host: IP Parameter: \\<parameter> |\n| -10009     | Invalid source IP address. |\n| -20001     | Invalid Request: CustomerID Parameter: <customer_id> |\n| -20002     | This product is not enabled for this Customer ID.  |\n| -30000     | Invalid Customer ID.     |\n| -30001     | Customer ID Account Suspended.                     |\n| -30002     | Customer ID Account Not Activated.                 |\n| -30003     | Customer ID new account limit reached.             |\n| -30004     | Missing required 'Authorization' header |\n| -30005     | Required 'Authorization' header is not in the correct format |\n| -30006     | Invalid Signature |\n| -30007     | Missing required 'Date' or 'x-ts-date' header    |\n| -30008     | Invalid 'x-ts-auth-method' header. |\n| -30009     | 'Date' or 'x-ts-date' header is not RFC822 compliant |\n| -30010     | 'Date' or 'x-ts-date' header is not within tolerable range |\n| -30011     | 'x-ts-nonce' header value is either too long or too short |\n| -30012     | 'x-ts-nonce' header value has been used recently |\n| -30015     | Invalid API Key. |\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/getStatusResponse"},{"type":"object","properties":{"signature_string":{"type":"string","description":"Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.","example":"GET\\n\\nTue, 31 Jan 2024 19:36:42 GMT\\nx-ts-auth-method: HMAC-SHA256\\n/v1/verify/0123456789ABCDEF0123456789ABCDEF"}}}]},"examples":{"Unauthorized":{"value":{"reference_id":null,"sub_resource":null,"errors":[{"code":-30004,"description":"Missing required 'Authorization' header"}],"status":{"code":501,"description":"Not authorized","updated_on":"2022-31-03T14:51:28.709526Z"}}}}}}},"404":{"description":"Not found. The server has not found anything matching the request URI. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Error Code | Associated text string   |\n|------------|--------------------------|\n| -10001     | CustomerID/ReferenceID not found |\n| -10001     | CustomerID/ReferenceID not found: CustomerID/ReferenceID Parameter: \\<parameter> |\n| -10004     | Reference ID expired.     |\n\nAssociated text string for -10001 will change depending on the parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getStatusResponse"},"examples":{"Not found":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"","errors":[{"code":-10004,"description":"ReferenceID expired."}],"status":{"code":599,"description":"Status not available","updated_on":"2022-31-03T14:51:28.709526Z"}}}}}}},"429":{"description":"Too many requests. The user sent too many requests in a given amount of time. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Error Code | Associated text string   |\n|------------|--------------------------|\n| -40007     | Rate Limit Exceeded  |\n| -40008     | \\<product> exceeded transaction hard cap. Request denied.  |","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getStatusResponse"},"examples":{"Rate Limit Exceeded":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"","errors":[{"code":-40007,"description":"Rate Limit Exceeded"}],"status":{"code":500,"description":"Transaction not attempted","updated_on":"2022-31-03T14:51:28.709526Z"}}}}}}},"503":{"description":"Service unavailable. The system is unavailable, try again. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Error Code | Associated text string   |\n|------------|--------------------------|\n| -90001     | System Unavailable, please try again later.  |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getStatusResponse"},"examples":{"System Unavailable":{"value":{"reference_id":null,"sub_resource":null,"errors":[{"code":-90001,"description":"System Unavailable, Please try again later."}],"status":{"code":500,"description":"Transaction not attempted","updated_on":"2022-31-03T14:51:28.709526Z"}}}}}}}},"operationId":"getSMSVerifyStatus","description":"Get delivery status and other details for a Telesign SMS Verify API transaction that you have created. Use this endpoint also to complete verification, if Telesign generated your code.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) (easiest to implement) or [Digest](/enterprise/docs/authentication#digest-authentication)\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Accepts:** `application/x-www-form-urlencoded`\n* **Required headers:** `Content-Type - application/x-www-form-urlencoded`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)\n","tags":["Transaction Status"],"parameters":[{"schema":{"type":"string","example":"57244"},"in":"query","name":"verify_code","description":"If Telesign generated the code sent to your end user, include the asserted verification code from your end user here. "}]}},"/v1/verify/completion/{reference_id}":{"put":{"description":"Use this action to notify Telesign that you have completed verification with the SMS Verify API for an end-user. This is for a verification transaction where you generated the verification code yourself.\n\n## General requirements\n* **Authentication:** [Basic](/enterprise/docs/authentication#basic-authentication) (easiest to implement) or [Digest](/enterprise/docs/authentication#digest-authentication)\n* **Encoding:** Accepts only **UTF-8 unicode** characters as inputs.\n* **Responds with:** `application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)","parameters":[{"in":"path","name":"reference_id","required":true,"description":"The reference ID for the transaction you want to provide completion data about.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.\n           \n| Status code | Description                                      |\n|-------------|--------------------------------------------------|\n| 1900        | Verify completion successfully recorded  |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/putCompletionResponse"}}}},"400":{"description":"Bad request. The request could not be understood by the server due to malformed syntax. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Status code | Associated text string |\n|--|--|\n| -10001 | Invalid parameter passed |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorObject"}}}},"401":{"description":"Unauthorized. The request requires user authentication. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n | Status code | Associated text string | \n |-------------|------------------------|\n | -30000 | Invalid customer ID |\n | -30001 | Account suspended | \n | -30002 | Account not activated |\n | -30003 | Account limit reached | \n | -30004 | Missing required Authorization header |\n | -30005 | Required Authorization header is not in the correct format | \n | -30006 | Invalid signature | \n | -30007 | Missing required Date or X-TS-Date header | \n | -30008 | Invalid X-TS-Auth-Method header | \n | -30009 | Date or X-TS-Date header is not [RFC822 compliant](https://www.w3.org/Protocols/rfc822/) | \n | -30010 | Date or X-TS-Date header is not within tolerable range |\n | -30011 | X-TS-Nonce header value is either too long or too short | \n | -30012 | X-TS-Nonce header value has been used recently |\n | -30013 | Invalid ReferenceID for Verify Completion |\n \n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/errorObject"},{"type":"object","properties":{"signature_string":{"type":"string","description":"Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.","example":"PUT\\n\\nTue, 31 Jan 2024 19:36:42 GMT\\nx-ts-auth-method: HMAC-SHA256\\n/v1/verify/completion/0123456789ABCDEF0123456789ABCDEF"}}}]}}}},"404":{"description":"Not found. The server has not found anything matching the request URI. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Status code | Associated text string | \n|-------------|------------------------|\n| -10001       | Customer ID / Reference ID not found           |\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorObject"}}}},"503":{"description":"Service unavailable. The system is unavailable, try again. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/statusObject"},"error":{"$ref":"#/components/schemas/errorObject"}}},"examples":{"System Unavailable":{"value":{"status":{"code":500,"description":"Transaction not attempted"},"error":{"code":-90001,"description":"System Unavailable, Please try again later."}}}}}}}},"summary":"Report completion","tags":["Completions"],"operationId":"reportSMSVerifyCompletion"},"parameters":[{"name":"reference_id","in":"path","required":true,"schema":{"type":"string"}}]}},"components":{"schemas":{"putCompletionResponse":{"type":"object","title":"putCompletionResponse","properties":{"reference_id":{"type":"string","description":"A unique, randomly generated hex value that identifies your web service request.","minLength":32,"maxLength":32},"subresource":{"type":"string","description":"The subresource in the URI path from your original request to initiate this transaction. Indicates which form of verification you used.","example":"sms"},"errors":{"type":"array","description":"Contains an object for each error condition that resulted from the request.","items":{"$ref":"#/components/schemas/errorObject"}},"status":{"type":"object","description":"Contains details about the request status.","properties":{"code":{"type":"string","description":"A numeric code indicating the processing status of this request."},"description":{"type":"string","description":"A text description of the status code."},"updated_on":{"type":"string","description":"An [RFC 3339](http://www.ietf.org/rfc/rfc3339.txt) timestamp indicating when the request status was updated. "}},"required":["code","description","updated_on"]}}},"additionalInfo":{"type":"object","title":"additionalInfo","description":"Contains properties relevant when the message sent with this transaction is one of several parts of a longer message that was split. This object only appears if this feature is enabled for your account. Contact our [Customer Support Team](mailto:support@telesign.com) to request this feature.","properties":{"message_part_sequence_number":{"type":"integer","example":1,"description":"Indicates this message's position in the series of split parts."},"message_parts_count":{"type":"integer","example":2,"description":"The total number of split parts for the longer message. If the message is not split, this value is `1`."},"message_parts_reference_ids":{"type":"string","example":"35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12","description":"The reference IDs for each part of the longer message, separated by commas."}}},"getStatusResponse":{"type":"object","title":"getStatusResponse","properties":{"reference_id":{"type":"string","description":"A unique, randomly generated hex value that identifies your web service request.","nullable":true},"sub_resource":{"type":"string","description":"The subresource accessed for the request. This is always `sms` for the SMS Verify API.","nullable":true},"errors":{"type":"array","description":"Contains an object for each error condition that resulted from the request.","items":{"$ref":"#/components/schemas/errorObject"}},"status":{"type":"object","description":"Contains details about the request status.","required":["code","description","updated_on"],"properties":{"code":{"type":"integer","description":"A numeric code indicating the processing status of this request."},"description":{"type":"string","description":"Text describing the transaction status."},"updated_on":{"type":"string","description":"An <a href=\"http://www.ietf.org/rfc/rfc3339.txt\">RFC 3339</a> timestamp indicating when the transaction status was updated."}}},"verify":{"type":"object","description":"Contains properties about the status of the verification attempt by the end user (if any).","properties":{"code_state":{"type":"string","description":"Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. Possible values are: \n* `VALID` - The codes match. \n* `INVALID` - The codes do not match.\n* `EXPIRED` - The match was attempted after the end of the validity period for the code.\n* `MAX_ATTEMPTS_EXCEEDED` - The match was attempted after the end user already had made the maximum allowed number of attempts for the code.\n* `UNKNOWN` - Any other state.","enum":["VALID","INVALID","UNKNOWN","EXPIRED","MAX_ATTEMPTS_EXCEEDED"],"example":"VALID"},"code_entered":{"type":"string","description":"If the end user entered a code, what they entered is provided here.","example":"45558"}}},"additional_info":{"$ref":"#/components/schemas/additionalInfo"}},"required":["reference_id","sub_resource","errors","status"]},"SMSVerifySuccessResponse":{"title":"SMSVerifySuccessResponse","allOf":[{"type":"object","properties":{"verify":{"type":"object","description":"Contains properties related to the verification status.","properties":{"code_state":{"type":"string","description":"Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. At this point in the verification process, the status is always `UNKNOWN`.","enum":["UNKNOWN"],"example":"UNKNOWN"},"code_entered":{"type":"string","description":"Always set to an empty string. There is no code entered by the end user at this point in the verification process."}}}}},{"$ref":"#/components/schemas/VerifyPlusResPackages"}],"x-examples":{}},"ScoreNumbering":{"title":"ScoreNumbering","type":"object","description":"Contains properties related to the numbering attributes of the specified phone number. This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"original":{"type":"object","description":"Contains details about the original phone number included in the request.","properties":{"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"},"complete_phone_number":{"type":"string","description":"The base phone number prefixed with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"17833012348"},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for the United Kingdom is `44`.","example":"1"}}},"cleansing":{"type":"object","description":"Contains details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.","properties":{"call":{"type":"object","description":"Contains cleansing details for the phone number if it is enabled to receive voice calls.","properties":{"cleansed_code":{"type":"integer","description":"One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.","example":100},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.","example":"1"},"max_length":{"type":"integer","description":"The maximum number of digits allowed for phone numbers with this country dialing code.","example":10},"min_length":{"type":"integer","description":"The minimum number of digits allowed for phone numbers with this country dialing code.","example":10},"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"}}},"sms":{"type":"object","description":"Contains cleansing details for the phone number if it is enabled to receive SMS.","properties":{"cleansed_code":{"type":"integer","description":"One of the [phone number cleansing codes](/enterprise/docs/codes-languages-and-time-zones#phone-number-cleansing-codes) specifying the cleansing operation performed on the phone number.","example":100},"country_code":{"type":"string","description":"The 1, 2, or 3-digit [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes). For example, the country dialing code for both the U.S.A. and Canada is `1`, and the country dialing code for United Kingdom is `44`.","example":"1"},"max_length":{"type":"integer","description":"The maximum number of digits allowed for phone numbers with this country dialing code.","example":10},"min_length":{"type":"integer","description":"The minimum number of digits allowed for phone numbers with this country dialing code.","example":10},"phone_number":{"type":"string","description":"The base phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).","example":"7833012348"}}}}}}},"ScorePhoneType":{"title":"ScorePhoneType","type":"object","description":"This object is only included if enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"code":{"type":"string","description":"One of the [phone type codes](/enterprise/docs/codes-languages-and-time-zones#phone-type-codes).","example":"2"},"description":{"type":"string","description":"Text describing the phone type.","example":"MOBILE"}}},"ScoreRisk":{"title":"ScoreRisk","type":"object","description":"Contains properties related to the risk score for the specified phone number. Only returned when this feature has been enabled by the [Telesign Customer Support Team](mailto:support@telesign.com).","properties":{"level":{"type":"string","example":"low","description":"The severity of the risk. [Score Scales](/enterprise/docs/intelligence-get-started#score-scales) provides a table with risk levels."},"recommendation":{"type":"string","description":"The action that Telesign recommends that you take based on the risk score.","example":"allow","enum":["allow","flag","block"]},"score":{"type":"integer","description":"The risk score for this phone number."}}},"errorObject":{"type":"object","title":"errorObject","description":"Contains properties related to an error that occurred during processing of the request.","properties":{"code":{"type":"integer","description":"A numeric code specifying which error occurred.","example":-10001},"description":{"type":"string","description":"Text describing the error that occurred.","example":"Invalid Request: PhoneNumber Parameter"}}},"SIMSwapResponse":{"type":"object","title":"SIMSwapResponse","description":"Properties related to the SIM Swap check for this transaction. This is only included if enabled by our [Customer Support Team](mailto:support@telesign.com).","properties":{"swap_date":{"type":"string","description":"The date of the SIM swap, if one is detected. ","example":"2018-09-05"},"swap_time":{"type":"string","description":"The time of the SIM swap, if one is detected. ","example":"22:00:00"},"risk_indicator":{"type":"integer","description":"Indicates the likelihood that a SIM swap occured for this number. The response ranges between `1` and `4`.\n* `1` - **(very low)** Swap did not occur or it occurred 15+ days ago. \n* `2` - **(low)** Swap occurred between 3 and 14 days ago. \n* `3` - **(medium)** Swap occurred in the last 72 hours. \n* `4` - **(high)** Swap occurred in the last 24 hours.","example":1},"status":{"type":"object","description":"Contains properties related to the status of the SIM Swap check.","properties":{"code":{"type":"integer","description":"A code indicating the status of your request. ","example":2800},"description":{"type":"string","description":"Description of the status of your request.","example":"Request successfully completed"}}}}},"sharedResponseSchema":{"title":"sharedResponseSchema","type":"object","description":"","properties":{"reference_id":{"type":"string","description":"A unique, randomly generated hex value that identifies your web service request.","example":"0123456789ABCDEF0123456789ABCDEF","minLength":32,"maxLength":32},"sub_resource":{"type":"string","example":"sms","description":"The subresource in the URL accessed by this request."},"errors":{"type":"array","description":"Contains an object specifying each error that occurred. If no errors occurred, the array is empty.","items":{"$ref":"#/components/schemas/errorObject"}},"status":{"type":"object","description":"Contains properties describing the preliminary delivery status of the SMS you sent.","properties":{"updated_on":{"type":"string","description":"An RFC 3339 timestamp indicating when the delivery status was last updated. ","example":"2020-08-27T17:28:49.559307Z"},"code":{"type":"integer","description":"A numeric code indicating the delivery status of the SMS.","example":290},"description":{"type":"string","description":"Text describing the delivery status of the SMS.","example":"Message in progress"}},"required":["updated_on","code","description"]}}},"401ResponseSchema":{"title":"401ResponseSchema","type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","example":-10009},"description":{"type":"string","example":"Invalid source IP address"}}}},"status":{"type":"object","properties":{"code":{"type":"integer","example":500},"description":{"type":"string","example":"Transaction not attempted"}}}}},"VerifyPlusResPackages":{"title":"VerifyPlusResPackages","type":"object","properties":{"phone_type":{"$ref":"#/components/schemas/ScorePhoneType"},"numbering":{"$ref":"#/components/schemas/ScoreNumbering"},"risk":{"$ref":"#/components/schemas/ScoreRisk"}}},"statusObject":{"title":"statusObject","type":"object","description":"Contains properties related to the processing status of the transaction.","properties":{"code":{"type":"integer","description":"A numeric code that indicates the status of your transaction."},"description":{"type":"string","description":"Text describing the status of your transaction."}},"required":["code","description"]}},"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Easiest to implement. See [Basic Authentication](/api-reference/authentication#basic-authentication) for more details."},"Digest":{"name":"Authorization","type":"apiKey","in":"header","description":"See [Digest Authentication](/api-reference/authentication#digest-authentication) for more details."}},"responses":{"200Response":{"description":"**Success.** Your request was fulfilled and resulted in a message being sent. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n \n | Status code | Associated text string | Description                                      |\n |-------------|------------------------|--------------------------------------------------|\n | 290         | Message in progress    | The message is being sent to the SMS gateway.    |\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"$ref":"#/components/schemas/SMSVerifySuccessResponse"}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":290,"description":"Message in progress"},"verify":{"code_state":"UNKNOWN","code_entered":""}}}}}}},"400Response":{"description":"**Bad request.** The request could not be understood by the server due to malformed syntax. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n\n| Status code | Status description   | Error code | Description   |\n|------------|--------------------------|------------|--------------------------|\n| 500 | Transaction not attempted | -10001     | Invalid Request: {parameter name} Parameter: {parameter value} |\n| 500 | Transaction not attempted | -10001     | Invalid Request: Missing Parameter: {parameter name} |\n| 500 | Transaction not attempted | -10001     | Invalid Request: {parameter name} Parameter                 |\n| 500 | Transaction not attempted | -10001     | Not Allowed Host: IP/Hostname Parameter: {host_ip_address}/{host_name} |\n| 500 | Transaction not attempted | -40006     | Bad request              |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[{"code":-10001,"description":"Invalid Request: PhoneNumber Parameter"}],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":500,"description":"Transaction not attempted"}}}}}}},"429Response":{"description":"**Too many requests.** The user sent too many requests in a given amount of time. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Status code | Status description   | Error code | Description   |\n|------------|--------------------------|------------|--------------------------|\n| 500 | Transaction not attempted | -40007     | Rate Limit Exceeded   |\n| 500 | Transaction not attempted | -40008     | Verify SMS exceeded transaction hard cap. Request denied.         |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","example":-40008},"description":{"type":"string","example":"SMS Verify exceeded transaction hard cap. Request denied. "}}}},"status":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"}}}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[{"code":-40008,"description":"SMS Verify exceeded transaction hard cap. Request denied. "}],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":500,"description":"Transaction not attempted"}}}}}}},"500Response":{"description":"**Service unavailable.** The system is unavailable, try again. Code against the Telesign status or error codes from the `status.code` and `errors.code` properties in the response payload, rather than the HTTP status code of the response.\n\n| Status code | Status description   | Error code | Description   |\n|------------|--------------------------|------------|--------------------------|\n| 500 | Transaction not attempted | -90001  | System Unavailable, please try again later.  |","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/sharedResponseSchema"},{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"integer","example":-10004},"description":{"type":"string","example":"Reference ID expired"}}}},"status":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"}}},"signature_string":{"type":"string","description":"Returned when request signature is not valid. Signature from failed authorization requests - doesn’t contain all required data (like x-ts-auth-method), or it’s not ordered properly.","example":"POST\\napplication/x-www-form-urlencoded\\n\\nx-ts-auth-method: HMAC-SHA256\\nx-ts-date:Tue, 31 Jan 2024 11:36:42 GMT\\nx-ts-nonce:ab$CDef/gh123+II4jk\\nphone_number=11234567890\\n/v1/verify/sms"}}}]},"examples":{"Example":{"value":{"reference_id":"0123456789ABCDEF0123456789ABCDEF","sub_resource":"sms","errors":[{"code":-10004,"description":"Reference ID expired"}],"status":{"updated_on":"2020-08-27T17:28:49.559307Z","code":500,"description":"Transaction not attempted"}}}}}}}}},"security":[{"Basic":[]}],"x-readme":{"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true},"tags":[{"name":"Messages"},{"name":"Completions"},{"name":"Transaction Status"}]}