--- title: Send Link slug: us-apis/send-link description: This document provides detailed information on an API that generates verification links to be sent via SMS for consumer authentication. It covers the requirements, sample requests, response and error parameters, as well as contact information for further createdAt: 2023-01-31T12:44:28.000Z --- ## Introduction This API returns a link to be sent via SMS to the consumer that serves as a verification mechanism. The generated link is sent to the mobile number provided by the customer via an SMS. The consumer then clicks on the link to begin the authentication & gets redirected to the target URL provided. ### Requirements Start the process by capturing the phone number from the consumer so you can generate the one-time, fortified link for that specific number. This is generally done via a web form or otherwise obtained via your consumer records. Please find an example of end user form below. ::Image[]{src="https://api.archbee.com/api/optimize/w0YdjmC6Uxu0AJ6sPj9OT/5mTWO2AZhgxnOnI5h9UPC_db88578-mobilenumber.png" size="22" width="397" height="580" position="center" caption="Example End User Form" showCaption="true"} After obtaining the phone number, your web server should then initiate a request to the Send Instant Link API endpoint. As part of the request, the MobileNumber and a TargetUrl should be included. The TargetUrl is the destination the end user should be delivered to after they click on the link, where we redirect the web session upon completion of network authentication. It can be any custom URL that fits your preferred user experience; it simply needs to be able to capture the returned VFP. The fortified link will be sent via SMS to the consumer into an SMS body as visible in the screenshot below. ::Image[]{src="https://api.archbee.com/api/optimize/w0YdjmC6Uxu0AJ6sPj9OT/BMtKDHEIfOFL1jYbPM6jp_5bc6ea4-sms-link.png" size="34" width="334" height="592" position="center" showCaption="false"} :::hint{type="info"} Messaging here is key; you should highlight several things in your SMS message: - Identify the business in the message (i.e., “Here is your \{business name} authentication link.”). - Warn the consumer that they should only click on the link if they are expecting it - We can also recommend to customer to disconnet Wi-Fi before cliking for better results Default Verbiage is "Your Identitiy Verification journey has started, please click on the following link to verify possession of the device - \." ::: ## API Details You must first log in before sending the request. The authorization header in the request must include the access token obtained from the login API call. Need to pass the following information. **Providing targetUrl, mobileNumber and countryCode(**only valid values** 'US' **or** 'CA') is mandatory**. **sourceIp** is optional and can be used as an additional fraudulent detection indicator. - **targetUrl**(required) - **mobileNumber**(required) - **sourceIp**(optional) - **customSms**(optional) - **countryCode**(required) ### Sample cURL ::::Tabs :::Tab{title="Production"} ```curl curl --location 'https://api.signzy.us/api/v3/us-kyc/send-instant-link' \ --header 'Content-Type: application/json' \ --header 'Authorization: ' \ --data '{ "targetUrl": "https://www.google.com", "mobileNumber": "2001001686", "countryCode": "US" }' ``` ::: :::Tab{title="Pre-Production"} ```curl curl --location 'https://api-preproduction.signzy.us/api/v3/us-kyc/send-instant-link' \ --header 'Content-Type: application/json' \ --header 'Authorization: ' \ --data '{ "targetUrl": "https://www.google.com", "mobileNumber": "2001001686", "countryCode": "US" }' ``` ::: :::: ### Request Body Parameters | **Parameter** | **Data Type** | **Required** | **Description** | | ------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | targetUrl | string | Yes | **Required **The URL of the client server that will be called back by the phone, providing the VFP for the result call | | mobileNumber | string | Yes | **Required **The phone number being queried.
(without leading plus sign & country code) | | countryCode | string | Yes | **Required **The country code associated. Only valid values allowed are 'US' or 'CA'. | ### Response Body Parameters | **Key** | **Type** | **Description** | | --------- | -------- | ------------------------------------------- | | requestId | string | The unique identifier for the request. | | sessionId | string | The session ID associated with the request. | ### Sample Response ```json { "result": { "requestID": "f64d44f8-3b0c-449c-8b79-9e2bbe0b2f3b", "sessionId": "f64d44f8-3b0c-449c-8b79-9e2bbe0b2f3b" } } ``` ### Sample Error :::CodeblockTabs targetUrl not passed ```json { "error": { "name": "error", "message": "targetUrl is required", "status": 400, "reason": "VALIDATION_ERROR", "type": "Bad Request", "statusCode": "400" } } ``` mobileNumber not passed ```json { "error": { "name": "error", "message": "mobileNumber is required", "status": 400, "reason": "VALIDATION_ERROR", "type": "Bad Request", "statusCode": "400" } } ``` countryCode not passed ```json { "error": { "name": "error", "message": "countryCode is required", "status": 400, "reason": "VALIDATION_ERROR", "type": "Bad Request", "statusCode": "400" } } ``` 503 ```json { "error": { "name": "error", "message": "Request cannot be processed at this time", "status": 503, "reason": "ERROR", "type": "Conflict", "statusCode": 503 } } ``` 400 ```json { "error": { "name": "error", "message": "Request parse failure", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 408 ```json { "error": { "name": "error", "message": "Request timeout", "status": 408, "reason": "ERROR", "type": "Conflict", "statusCode": 408 } } ``` 400 ```json { "error": { "name": "error", "message": "Parameter is invalid", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 404 ```json { "error": { "name": "error", "message": "Cannot identify subscriber", "status": 404, "reason": "ERROR", "type": "Conflict", "statusCode": 409 } } ``` 403 ```json { "error": { "name": "error", "message": "Subscriber is not found on the required whitelist", "status": 403, "reason": "ERROR", "type": "Conflict", "statusCode": 403 } } ``` 400 ```json { "error": { "name": "error", "message": "Subscriber is not supported for this service", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 400 ```json { "error": { "name": "error", "message": "ApiClient or Operator not enabled for this service", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 403 ```json { "error": { "name": "error", "message": "Subscriber is suspended", "status": 403, "reason": "ERROR", "type": "Conflict", "statusCode": 403 } } ``` 403 ```json { "error": { "name": "error", "message": "Subscriber is deactivated", "status": 403, "reason": "ERROR", "type": "Conflict", "statusCode": 403 } } ``` 403 ```json { "error": { "name": "error", "message": "Subscriber is not eligible for the service", "status": 403, "reason": "ERROR", "type": "Conflict", "statusCode": 403 } } ``` 404 ```json { "error": { "name": "error", "message": "No CRM data available", "status": 404, "reason": "ERROR", "type": "Conflict", "statusCode": 404 } } ``` 400 ```json { "error": { "name": "error", "message": "Carrier mismatch", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 400 ```json { "error": { "name": "error", "message": "Transaction has not completed", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 503 ```json { "error": { "name": "error", "message": "The external provider cannot be reached", "status": 503, "reason": "ERROR", "type": "Conflict", "statusCode": 503 } } ``` 404 ```json { "error": { "name": "error", "message": "Not a valid or active number", "status": 400, "reason": "ERROR", "type": "Conflict", "statusCode": 400 } } ``` 409 Upstream Down ```json { "error": { "name": "error", "message": "Upstream Down", "status": 409, "reason": "ERROR", "type": "Conflict", "statusCode": 409 } } ``` ::: ### Error Response Parameters | **Parameter** | **Description** | | ---------------- | ---------------------------------- | | error | This parameter contains the error. | | error.name | the error name. | | error.message | the error message. | | error.status | Status of the api | | error.reason | Reason for error | | error.type | Type of the error | | error.statusCode | Request Status code from Signzy | :::hint{type="info"} ### Getting help Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better. You can reach out to us at [help@signzy.com](#). We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively. We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you! :::