{"_id":"59ca571a8fde45001066049e","project":"54eb50e5615ffc1900305a16","version":{"_id":"54eb63b859b1172100334fae","project":"54eb50e5615ffc1900305a16","forked_from":"54eb63a1867e1917009b711d","__v":28,"createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03","589b19b4fec2730f0082e040","58b04a023529383900a759b5","58b92d1598157a0f004869bf","592e7685c58275000f20174f","59392839e376d4002f8a0474","59393064e376d4002f8a05a1","5947ae0d4005e2000f3a4fec","594a74df1d1de5001ab3517a","5954bc387a147f001b918915","59b8eeeb707542001076d3b6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"category":{"_id":"5624bbb785a31117001c5403","pages":["5653264657978b1700df716a","5655bcf8dd82540d00278c26","5655bfd81a06b61900c66873","5655c7c0a66be71700968dd7","5660588e4320a80d00bec124","56618ad455e4450d00e62b89","56f1685a2a85600e00ea3dca"],"project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","__v":7,"sync":{"url":"","isSync":false},"reference":true,"createdAt":"2015-10-19T09:45:27.364Z","from_sync":false,"order":11,"slug":"2-factor-authentication","title":"2-factor authentication"},"user":"54eb4fdedf7add210007b29b","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-26T13:33:14.334Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":true,"order":19,"body":"Once you've created a 2FA application and message template, you are ready to start using the 2FA service and send PIN codes to end users. You can send PINs as SMS or Voice message.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"After sending out the PIN message, use the Verify PIN method to verify the PIN returned by the recipient. Learn all about the 2FA process in the 2FA introduction.\"\n}\n[/block]\nOn this page you will learn how to:\n\n* [Send PIN over SMS](#section-resource)\n* [Resend PIN over SMS](#resend-pin-over-sms)\n* [Send PIN over Voice](#send-pin-over-voice)\n* [Resend PIN over Voice](http://google.com)\n* [Verify PIN](#verify-pin)\n\n## Resource\n\n```\nhttps://api.infobip.com/2fa/1/pin\n```\n\n##Resource description\n\n|Parameter|Type|Description|\n|-|-|-|\n|*to* *|string|Phone number to which 2FA message will be sent. Example: 41793026727.|\n|*applicationId**|string|2FA application ID|\n|*messageId* *|string|Message template ID that will be sent to a phone number|\n|*from*|string|Sender ID in numeric or alphanumeric format. If this parameter is not set, it will be automatically filled from the created message parameter sender.|\n|*ncNeeded*|boolean|Indicates if Number Lookup is needed before sending 2FA message. If the parameter value is `true`, Number Lookup will be requested before sending SMS. If the value is `false`, SMS will be sent without requesting Number Lookup<br>Default value: `true`.|\n|*ncStatus*|string|Status of sent Number Lookup. Number Lookup status can have one of the following values: `NC_DESTINATION_UNKNOWN`, `NC_DESTINATION_REACHABLE`, `NC_DESTINATION_NOT_REACHABLE`, `NC_NOT_CONFIGURED`. If you get `NC_NOT_CONFIGURED` status, you should contact your account manager. SMS will not be sent only if Number Lookup status is `NC_NOT_REACHABLE`.|\n|*smsStatus*|string|Sent SMS status. Can have one of the following values: `MESSAGE_SENT`, `MESSAGE_NOT_SENT.`|\n|*pinId*|string|Sent PIN code ID.|\n|*callStatus*|string|Call status. [View possible call status codes](#section-call-status-codes).|\n\n\n### Call status codes\n\n|Value|Description|\n|:---|:---|\n|`BAD_REQUEST`|Provided request does not meet required conditions.|\n|`PROCESSING`|Request is currently being processed.|\n|`PROCESSED`|Request is successfully processed and answered by human.|\n|`ANSWERED_MACHINE`|Request is successfully processed and answered by machine.|\n|`ERROR`|System error occurred during processing.|\n|`ERROR_NOT_ENOUGH_CREDITS`|Not enough credits on account balance to pay for the call.|\n|`ERROR_NETWORK_NOT_AVAILABLE`|We could not find network for given destination address.|\n|`ERROR_ROUTE_NOT_AVAILABLE`|Route for TTS call is not set up on account.|\n|`ERROR_USER_BUSY`|User was busy during call attempt(s).|\n|`ERROR_NO_ANSWER`|User did not answer call(s).|\n|`UNDEFINED`|Request is undefined.|\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Application configuration warning\",\n  \"body\": \"When sending out PIN messages, one of the common HTTP response messages is 429 Too Many Requests. The source of this message is often a security feature put in place on the application level. If you get too many 429 messages, please review your Application settings.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Send PIN over SMS\"\n}\n[/block]\nThis method allows you to generate and send a PIN code over SMS to the provided destination address.\n\n```\nPOST https://api.infobip.com/2fa/1/pin\n```\n\n##Request example\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /2fa/1/pin?ncNeeded=true HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\\nContent-Type: application/json\\n\\n{\\n  \\\"applicationId\\\": \\\"HJ675435E3A6EA43432G5F37A635KJ8B\\\",\\n  \\\"messageId\\\": \\\"0130269F44AFD07AEBC2FEFEB30398A0\\\",\\n  \\\"from\\\": \\\"InfoSMS\\\",\\n  \\\"to\\\": \\\"41793026727\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"pinId\\\": \\\"9C817C6F8AF3D48F9FE553282AFA2B67\\\",\\n  \\\"to\\\": \\\"41793026727\\\",\\n  \\\"ncStatus\\\": \\\"NC_DESTINATION_REACHABLE\\\",\\n  \\\"smsStatus\\\": \\\"MESSAGE_SENT\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200 OK - JSON\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Resend PIN over SMS\"\n}\n[/block]\nThis method allows you to resend the already created PIN over SMS.\n\n```\nPOST https://api.infobip.com/2fa/1/pin/{pinId}/resend\n```\n\n##Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\\nContent-Type: application/json\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"to\\\": \\\"41793026727\\\",\\n  \\\"ncStatus\\\": \\\"NC_DESTINATION_REACHABLE\\\",\\n  \\\"smsStatus\\\": \\\"MESSAGE_SENT\\\",\\n  \\\"pinId\\\": \\\"9C817C6F8AF3D48F9FE553282AFA2B67\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Send PIN over Voice\"\n}\n[/block]\nThis method allows you to generate and send a PIN code over Voice to the provided destination address.\n\n```\nPOST https://api.infobip.com/2fa/1/pin/voice\n```\n\n##Request example\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /2fa/1/pin/voice HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\\nContent-Type: application/json\\nAccept: application/json\\n\\n{\\n  \\\"applicationId\\\": \\\"HJ675435E3A6EA43432G5F37A635KJ8B\\\",\\n  \\\"messageId\\\": \\\"0130269F44AFD07AEBC2FEFEB30398A0\\\",\\n  \\\"from\\\": \\\"41793012321\\\",\\n  \\\"to\\\": \\\"41793026727\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"pinId\\\": \\\"9C817C6F8AF3D48F9FE553282AFA2B67\\\",\\n  \\\"to\\\": \\\"41793026727\\\",\\n  \\\"callStatus\\\": \\\"PENDING_ACCEPTED\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200 OK - JSON\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Resend PIN over Voice\"\n}\n[/block]\nThis method allows you to resend the already created PIN over Voice.\n\n```\nPOST https://api.infobip.com/2fa/1/pin/{pinId}/resend/voice\n```\n\n##Request example\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend/voice HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\\nContent-Type: application/json\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"to\\\": \\\"41793026727\\\",\\n  \\\"pinId\\\": \\\"9C817C6F8AF3D48F9FE553282AFA2B67\\\",\\n  \\\"callStatus\\\": \\\"PROCESSED\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200 OK - JSON\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Verify PIN\"\n}\n[/block]\nThis method allows you to verify the received PIN.\n\n```\nPOST https://api.infobip.com/2fa/1/pin/{pinId}/verify\n```\n\n##Request example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/verify HTTP/1.1\\nHost: api.infobip.com\\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\\nContent-Type: application/json\\n\\n{\\n  \\\"pin\\\":\\\"1598\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nResponse\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"pinId\\\": \\\"9C817C6F8AF3D48F9FE553282AFA2B67\\\",\\n  \\\"msisdn\\\": \\\"41793026727\\\",\\n  \\\"verified\\\": true,\\n  \\\"attemptsRemaining\\\": 0\\n}\",\n      \"language\": \"json\",\n      \"name\": \"200 OK - JSON\"\n    }\n  ]\n}\n[/block]\nResponse description\n\n|Parameter|Type|Description|\n|-|-|-|\n|*pinId*|String|Sent PIN code ID.|\n|*msisdn*|String|Phone number (msisdn) to which 2FA message was sent.|\n|*verified*|Boolean|Indicates if the phone number (msisdn) was successfully verified.|\n|*attemptsRemaining*|Integer|Number of remaining PIN attempts.|\n|*pinError*|String|Indicates if any error occurs during PIN verification. <br>PIN error can have one of the following values: `WRONG_PIN`, `TTL_EXPIRED`, `NO_MORE_PIN_ATTEMPTS`|","excerpt":"Send 2FA PINs over SMS or Voice channels","slug":"send-and-verify-2fa-pin","type":"basic","title":"Send and verify PIN"}

Send and verify PIN

Send 2FA PINs over SMS or Voice channels

Once you've created a 2FA application and message template, you are ready to start using the 2FA service and send PIN codes to end users. You can send PINs as SMS or Voice message. [block:callout] { "type": "info", "body": "After sending out the PIN message, use the Verify PIN method to verify the PIN returned by the recipient. Learn all about the 2FA process in the 2FA introduction." } [/block] On this page you will learn how to: * [Send PIN over SMS](#section-resource) * [Resend PIN over SMS](#resend-pin-over-sms) * [Send PIN over Voice](#send-pin-over-voice) * [Resend PIN over Voice](http://google.com) * [Verify PIN](#verify-pin) ## Resource ``` https://api.infobip.com/2fa/1/pin ``` ##Resource description |Parameter|Type|Description| |-|-|-| |*to* *|string|Phone number to which 2FA message will be sent. Example: 41793026727.| |*applicationId**|string|2FA application ID| |*messageId* *|string|Message template ID that will be sent to a phone number| |*from*|string|Sender ID in numeric or alphanumeric format. If this parameter is not set, it will be automatically filled from the created message parameter sender.| |*ncNeeded*|boolean|Indicates if Number Lookup is needed before sending 2FA message. If the parameter value is `true`, Number Lookup will be requested before sending SMS. If the value is `false`, SMS will be sent without requesting Number Lookup<br>Default value: `true`.| |*ncStatus*|string|Status of sent Number Lookup. Number Lookup status can have one of the following values: `NC_DESTINATION_UNKNOWN`, `NC_DESTINATION_REACHABLE`, `NC_DESTINATION_NOT_REACHABLE`, `NC_NOT_CONFIGURED`. If you get `NC_NOT_CONFIGURED` status, you should contact your account manager. SMS will not be sent only if Number Lookup status is `NC_NOT_REACHABLE`.| |*smsStatus*|string|Sent SMS status. Can have one of the following values: `MESSAGE_SENT`, `MESSAGE_NOT_SENT.`| |*pinId*|string|Sent PIN code ID.| |*callStatus*|string|Call status. [View possible call status codes](#section-call-status-codes).| ### Call status codes |Value|Description| |:---|:---| |`BAD_REQUEST`|Provided request does not meet required conditions.| |`PROCESSING`|Request is currently being processed.| |`PROCESSED`|Request is successfully processed and answered by human.| |`ANSWERED_MACHINE`|Request is successfully processed and answered by machine.| |`ERROR`|System error occurred during processing.| |`ERROR_NOT_ENOUGH_CREDITS`|Not enough credits on account balance to pay for the call.| |`ERROR_NETWORK_NOT_AVAILABLE`|We could not find network for given destination address.| |`ERROR_ROUTE_NOT_AVAILABLE`|Route for TTS call is not set up on account.| |`ERROR_USER_BUSY`|User was busy during call attempt(s).| |`ERROR_NO_ANSWER`|User did not answer call(s).| |`UNDEFINED`|Request is undefined.| [block:callout] { "type": "warning", "title": "Application configuration warning", "body": "When sending out PIN messages, one of the common HTTP response messages is 429 Too Many Requests. The source of this message is often a security feature put in place on the application level. If you get too many 429 messages, please review your Application settings." } [/block] [block:api-header] { "title": "Send PIN over SMS" } [/block] This method allows you to generate and send a PIN code over SMS to the provided destination address. ``` POST https://api.infobip.com/2fa/1/pin ``` ##Request example [block:code] { "codes": [ { "code": "POST /2fa/1/pin?ncNeeded=true HTTP/1.1\nHost: api.infobip.com\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\nContent-Type: application/json\n\n{\n \"applicationId\": \"HJ675435E3A6EA43432G5F37A635KJ8B\",\n \"messageId\": \"0130269F44AFD07AEBC2FEFEB30398A0\",\n \"from\": \"InfoSMS\",\n \"to\": \"41793026727\"\n}", "language": "json" } ] } [/block] Response: [block:code] { "codes": [ { "code": "{\n \"pinId\": \"9C817C6F8AF3D48F9FE553282AFA2B67\",\n \"to\": \"41793026727\",\n \"ncStatus\": \"NC_DESTINATION_REACHABLE\",\n \"smsStatus\": \"MESSAGE_SENT\"\n}", "language": "json", "name": "200 OK - JSON" } ] } [/block] [block:api-header] { "title": "Resend PIN over SMS" } [/block] This method allows you to resend the already created PIN over SMS. ``` POST https://api.infobip.com/2fa/1/pin/{pinId}/resend ``` ##Request example [block:code] { "codes": [ { "code": "POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend HTTP/1.1\nHost: api.infobip.com\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\nContent-Type: application/json", "language": "json" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"to\": \"41793026727\",\n \"ncStatus\": \"NC_DESTINATION_REACHABLE\",\n \"smsStatus\": \"MESSAGE_SENT\",\n \"pinId\": \"9C817C6F8AF3D48F9FE553282AFA2B67\"\n}", "language": "json", "name": null } ] } [/block] [block:api-header] { "title": "Send PIN over Voice" } [/block] This method allows you to generate and send a PIN code over Voice to the provided destination address. ``` POST https://api.infobip.com/2fa/1/pin/voice ``` ##Request example [block:code] { "codes": [ { "code": "POST /2fa/1/pin/voice HTTP/1.1\nHost: api.infobip.com\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\nContent-Type: application/json\nAccept: application/json\n\n{\n \"applicationId\": \"HJ675435E3A6EA43432G5F37A635KJ8B\",\n \"messageId\": \"0130269F44AFD07AEBC2FEFEB30398A0\",\n \"from\": \"41793012321\",\n \"to\": \"41793026727\"\n}", "language": "json" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"pinId\": \"9C817C6F8AF3D48F9FE553282AFA2B67\",\n \"to\": \"41793026727\",\n \"callStatus\": \"PENDING_ACCEPTED\"\n}", "language": "json", "name": "200 OK - JSON" } ] } [/block] [block:api-header] { "title": "Resend PIN over Voice" } [/block] This method allows you to resend the already created PIN over Voice. ``` POST https://api.infobip.com/2fa/1/pin/{pinId}/resend/voice ``` ##Request example [block:code] { "codes": [ { "code": "POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/resend/voice HTTP/1.1\nHost: api.infobip.com\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\nContent-Type: application/json", "language": "json", "name": null } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"to\": \"41793026727\",\n \"pinId\": \"9C817C6F8AF3D48F9FE553282AFA2B67\",\n \"callStatus\": \"PROCESSED\"\n}", "language": "json", "name": "200 OK - JSON" } ] } [/block] [block:api-header] { "title": "Verify PIN" } [/block] This method allows you to verify the received PIN. ``` POST https://api.infobip.com/2fa/1/pin/{pinId}/verify ``` ##Request example [block:code] { "codes": [ { "code": "POST /2fa/1/pin/9C817C6F8AF3D48F9FE553282AFA2B67/verify HTTP/1.1\nHost: api.infobip.com\nAuthorization: App 003026bbc133714df1834b8638bb496e-8f4b3d9a-e931-478d-a994-28a725159ab9\nContent-Type: application/json\n\n{\n \"pin\":\"1598\"\n}", "language": "json" } ] } [/block] Response [block:code] { "codes": [ { "code": "{\n \"pinId\": \"9C817C6F8AF3D48F9FE553282AFA2B67\",\n \"msisdn\": \"41793026727\",\n \"verified\": true,\n \"attemptsRemaining\": 0\n}", "language": "json", "name": "200 OK - JSON" } ] } [/block] Response description |Parameter|Type|Description| |-|-|-| |*pinId*|String|Sent PIN code ID.| |*msisdn*|String|Phone number (msisdn) to which 2FA message was sent.| |*verified*|Boolean|Indicates if the phone number (msisdn) was successfully verified.| |*attemptsRemaining*|Integer|Number of remaining PIN attempts.| |*pinError*|String|Indicates if any error occurs during PIN verification. <br>PIN error can have one of the following values: `WRONG_PIN`, `TTL_EXPIRED`, `NO_MORE_PIN_ATTEMPTS`|