{"openapi":"3.0.0","info":{"title":"Engage API (Number Masking)","version":"1.0","description":"Use this service to create anonymous, limited-duration, SMS or voice communication-sessions between two end users without disclosing their phone numbers to each other. ","contact":{"name":"Telesign Customer Support Team","email":"support@telesign.com"}},"servers":[{"url":"https://rest-ww.telesign.com"}],"paths":{"/v1/anonymous/session/sms":{"post":{"summary":"Create masked SMS session","operationId":"createMaskedSMSSession","responses":{"200":{"$ref":"#/components/responses/resNumMask200"},"400":{"$ref":"#/components/responses/resNumMask400"},"429":{"$ref":"#/components/responses/resNumMask429"},"503":{"$ref":"#/components/responses/resNumMask503"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumMaskInputs"},"examples":{"Example":{"value":{"phone_number_1":"15555551212","phone_number_2":"15558675309","validity_period":500}}}},"application/xml":{"schema":{"type":"object","properties":{}}},"multipart/form-data":{"schema":{"type":"object","properties":{}}}},"description":""},"description":"Use this action to create an anonymous session for SMS communication with number masking. You must use SMS capable-only (not voice capable-only or dual-capable) numbers from Telesign as masking IDs when using this action. \n\n> Looking for the high-level guide page related to this action? Go to [Number Masking - Create masked session for SMS](/enterprise/docs/number-masking-create-masked-session-for-sms).\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/json`\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)","tags":["Number Masking"]},"parameters":[]},"/v1/anonymous/session/sms_voice":{"post":{"summary":"Create masked voice-SMS session","operationId":"createMaskedVoiceSMSSession","responses":{"200":{"$ref":"#/components/responses/resNumMask200"},"400":{"$ref":"#/components/responses/resNumMask400"},"429":{"$ref":"#/components/responses/resNumMask429"},"503":{"$ref":"#/components/responses/resNumMask503"}},"description":"Use this action to create an anonymous session, usable either for SMS or voice communication with number masking. You must use only dual-capable (both SMS and voice capable) numbers from Telesign as masking IDs when using this action. \n\n> Looking for the high-level guide page related to this action? Go to [Number Masking - Create masked session for SMS or voice](/enterprise/docs/number-masking-create-masked-session-for-sms-or-voice).\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/json`\n* **Responds with:** `application/json`\n* **Required headers:** `Content-Type - application/json`\n* **Rate limit:** [Default rate limits by product](https://support.telesign.com/s/article/do-you-have-any-rate-limits)","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumMaskInputs"}}}},"tags":["Number Masking"]}}},"components":{"schemas":{"NumMaskInputs":{"title":"NumMaskInputs","type":"object","properties":{"phone_number_1":{"type":"string","description":"The phone number for one of the end users that will engage in the anonymous exchange. ","example":"15555551212"},"phone_number_2":{"type":"string","description":"The phone number for the other end user that will engage in the anonymous exchange. Must be different from `phone_number_1`. ","example":"15558675309"},"validity_period":{"type":"integer","description":"The amount of time you want the two end users to be able to communicate for. The unit this number represents can be seconds, minutes, hours, or days. The unit used is configured by Telesign; ask our Customer Support Team if you need it changed. The maximum value depends on the units configured for your account, but will always be equivalent to 720 hours.","minimum":1,"example":500}}},"NumMaskStatus":{"title":"NumMaskStatus","type":"object","description":"Contains details related to the processing status of this transaction.","properties":{"code":{"type":"integer","description":"Numeric code indicating the processing status of the request.","example":2700},"description":{"type":"string","description":"Text describing the processing status of the request.","example":"Session successfully created"},"updated_on":{"type":"string","description":"A timestamp in ISO 8601 format indicating when the status was last updated.","example":"2018-02-12T14:57:11.765723Z"}}},"NumMaskSessionData":{"title":"NumMaskSessionData","type":"object","description":"Contains properties related to the session created for this request.","properties":{"session_end_on":{"type":"string","description":"The time stamp, in ISO 8601 format, indicating when the session will expire.","example":"2018-03-05 10:59:13.761245"},"resource":{"type":"string","description":"The Number Masking resource you used to create this session. If this value is `sms`, the session can only be used for SMS communication. If this value is `sms_voice`, the session can be used for either SMS or voice communication.","example":"sms","enum":["sms","sms_voice"]},"message":{"type":"string","description":"Any additional description of what happened during the creation of the session. For example, this value might give you a notification that the countries for phone number 1 and the assigned masking ID are different.","example":"Failed to obtain mask for 15555551212"},"phone_number_2":{"description":"One of the two phone numbers being masked in the anonymous session.","allOf":[{"$ref":"#/components/schemas/NumMaskPhoneNumberDetails"},{"type":"object","properties":{"complete_phone_number":{"type":"string","example":"15558675309"},"masked_id":{"type":"string","example":"15557740234","nullable":true}}}]},"validity":{"type":"string","description":"The period of time that the session will be available. Defined in terms of seconds, minutes, hours, or days. The unit used is configured by Telesign and can be changed at your request.","example":"500"},"phone_number_1":{"$ref":"#/components/schemas/NumMaskPhoneNumberDetails"}}},"NumMaskPhoneNumberDetails":{"title":"NumMaskPhoneNumberDetails","type":"object","properties":{"complete_phone_number":{"type":"string","description":"The base phone number prefixed with the country dialing code.","example":"15555551212"},"country_name":{"type":"string","description":"The country name associated with phone number.","example":"United States"},"country_iso3":{"type":"string","description":"The ISO 3166-1 three-letter country code associated with the phone number.","example":"USA"},"masked_id":{"type":"string","description":"The masking ID allocated to conceal this phone number.","example":"15557740233","nullable":true},"country_iso2":{"type":"string","description":"The ISO 3166-1 two-letter country code associated with the phone number.","example":"US"},"country_code":{"type":"string","description":"The one, two, or three-digit country dialing code.","example":"1"}}},"NumMaskResSchema":{"title":"NumMaskResSchema","type":"object","properties":{"reference_id":{"type":"string","description":"Unique 32-digit hex value generated by the service to identify both your request and the session created.","example":"B5862A14363C016C8832D53625270015"},"external_id":{"type":"string","example":"MSG432538","nullable":true},"status":{"$ref":"#/components/schemas/NumMaskStatus"},"session_data":{"$ref":"#/components/schemas/NumMaskSessionData"},"error":{"description":"Unused property. You can disregard this.","type":"string","nullable":true}}}},"securitySchemes":{"Basic":{"type":"http","scheme":"basic","description":"Easiest to implement. See [Basic Authentication](/enterprise/docs/authentication#basic-authentication) for more details."}},"responses":{"resNumMask200":{"description":"**Success.** Your request was fulfilled and resulted in the creation of a new session. 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 | Description |\n|--|--|\n| 2700 | Session successfully created |\n| 2701 | Session successfully created, the country codes of the phone number and assigned masked_id differs |","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumMaskResSchema"},"examples":{"Example":{"value":{"session_data":{"session_end_on":"2018-03-05 10:59:13.761245","resource":"sms","message":"","phone_number_2":{"complete_phone_number":"15558675309","country_name":"United States","country_iso3":"USA","masked_id":"15557740234","country_iso2":"US","country_code":"1"},"validity":"500","phone_number_1":{"complete_phone_number":"15555551212","country_name":"United States","country_iso3":"USA","masked_id":"15557740233","country_iso2":"US","country_code":"1"}},"reference_id":"B5862A14363C016C8832D53625270015","external_id":"MSG432538","status":{"code":2700,"description":"Session successfully created","updated_on":"2018-02-12T14:57:11.765723Z"},"error":null}}}}}},"resNumMask400":{"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 | Description |\n|--|--|\n| 2702 | Request for creating session failed, there isn't available masked_id |\n| 2703 | Request for creating session failed, invalid session type |\n| 2705 | Request for creating session failed, validity_period must be integer greater than zero |\n| 2706 | Request for creating session failed, phone number {phone_number} blocked by Telesign |\n| 2707 | Request for creating session failed, phone number {phone_number} blocked by customer |\n| 2708 | Request for creating session failed, phone_number_1 and phone_number_2 parameters cannot be the same value |\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/NumMaskResSchema"},{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"integer","example":2702},"description":{"type":"string","example":"Request for creating session failed, there isn't available masked_id"}}}}}]},"examples":{"Example":{"value":{"reference_id":"B5862A14363C016C8832D53625270015","external_id":"MSG432538","status":{"code":2702,"description":"Request for creating session failed, there isn't available masked_id","updated_on":"2018-02-12T14:57:11.765723Z"},"session_data":{"session_end_on":"2018-03-05 10:59:13.761245","resource":"sms","message":"Failed to obtain mask for 15555551212","phone_number_2":{"complete_phone_number":"15558675309","country_name":"United States","country_iso3":"USA","masked_id":null,"country_iso2":"US","country_code":"1"},"validity":"500","phone_number_1":{"complete_phone_number":"15555551212","country_name":"United States","country_iso3":"USA","masked_id":null,"country_iso2":"US","country_code":"1"}},"error":null}}}}}},"resNumMask503":{"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 | Description |\n|--|--|\n| 2704 | Request for creating session failed, internal error |\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/NumMaskResSchema"},{"type":"object","properties":{"status":{"type":"object","properties":{"code":{"type":"integer","example":2704},"description":{"type":"string","example":"Request for creating session failed, internal error"}}}}}]},"examples":{"Example":{"value":{"reference_id":"B5862A14363C016C8832D53625270015","external_id":"MSG432538","status":{"code":2704,"description":"Request for creating session failed, internal error","updated_on":"2018-02-12T14:57:11.765723Z"},"session_data":{"session_end_on":"2018-03-05 10:59:13.761245","resource":"sms","message":"","phone_number_2":{"complete_phone_number":"15558675309","country_name":"United States","country_iso3":"USA","masked_id":null,"country_iso2":"US","country_code":"1"},"validity":"500","phone_number_1":{"complete_phone_number":"15555551212","country_name":"United States","country_iso3":"USA","masked_id":null,"country_iso2":"US","country_code":"1"}},"error":null}}}}}},"resNumMask429":{"description":"Too many requests.","content":{"text/plain":{"schema":{"type":"string","description":"Too many requests.","example":"Too many requests."}}}}},"requestBodies":{}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true,"samples-enabled":true},"security":[{"Basic":[]}],"tags":[{"name":"Number Masking"}]}