openapi: 3.2.0
info:
  title: Telesign Delivery Reports API
  version: '1.0'
  contact:
    name: Telesign Customer Support Team
    email: support@telesign.com
  description: 'Operations tagged Delivery Reports across 4 of this provider''s published API definitions: telesign-sms-verify-api-callbacks-openapi.json, telesign-verify-api-callbacks-openapi.json, telesign-sms-verify-api-callbacks-openapi.yml, telesign-verify-api-callbacks-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://your-callback-url.com
tags:
- name: Delivery Reports
paths:
  /sms_verify_dlr_endpoint:
    parameters: []
    post:
      summary: Receive SMS Verify API Delivery Reports
      operationId: SMSVerifyCallbacks
      responses:
        '200':
          description: OK
      description: This is a web service created by you, to receive delivery reports (DLRs) from the Telesign SMS Verify API.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/DeliveryStatusNotification'
              - type: object
                properties:
                  sim_swap:
                    $ref: '#/components/schemas/SIMSwapResponse'
            examples:
              Example:
                value:
                  status:
                    code: 200
                    description: Delivered to handset
                    updated_on: '2016-10-21T14:05:36.181346Z'
                  submit_timestamp: '2016-01-01T01:01:01.010101Z'
                  errors: []
                  reference_id: B56259E45884010488343BAA15FB0002
                  verify:
                    code_state: UNKNOWN
                    code_entered: null
                  sub_resource: sms
                  additional_info:
                    message_parts_count: 1
                    price: '0.5112'
                    mnc: '004'
                    mcc: '310'
                    currency: USD
                    message_parts_reference_ids: 35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12
                    'sender_id ': '15558675310'
                  score_status:
                    phone_type:
                      code: '2'
                      description: MOBILE
                    risk:
                      recommendation: allow
                      score: 80
                      level: low
                    risk_insights:
                      status: 800
                      category:
                      - 10010
                      a2p:
                      - 22103
                      p2p:
                      - 30201
                      number_type:
                      - 0
                      ip:
                      - 0
                      email:
                      - 0
                    numbering:
                      phone_number: '1234567890'
                      min_length: 10
                      max_length: 10
                      country_code: '1'
                    location:
                      city: Los Angeles
                      county: Los Angeles County
                      state: CA
                      zip: '90066'
                      country:
                        iso2: US
                        iso3: USA
                        name: United States
                      time_zone:
                        name: America/Los_Angeles
                        utc_offset_max: '-8'
                        utc_offset_min: '-8'
                      coordinates:
                        latitude: 33.99791
                        longitude: -118.42302
                      metro_code: '4480'
                    blocklisting:
                      block_code: 0
                      block_description: Not blocked
                      blocked: false
                    carrier:
                      carrier_id: 309
                      name: AT&T Wireless
                  sim_swap:
                    swap_date: '2018-09-05'
                    swap_time: '22:00:00'
                    risk_indicator: '1'
                    status:
                      code: 2800
                      description: Request successfully completed
      tags:
      - Delivery Reports
    servers:
    - url: https://your-callback-url.com
  /verify_dlr_endpoint:
    post:
      summary: Receive Verify API Delivery Reports
      operationId: unifiedVerifyCallbacks
      responses:
        '200':
          description: OK
      description: This is a web service created by you, to receive delivery reports (DLRs) from the Telesign Verify API. You can receive callbacks, including DLRs, from multiple Telesign services at the same endpoint.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliveryStatusNotification_2'
            examples:
              Example:
                value:
                  created_on: '2022-31-03T14:51:28.709526Z'
                  inner_methods:
                  - method: whatsapp
                    state: FAILED
                    err_code: 3209
                    err_msg: Unknown status
                    tried_on: '2022-31-03T14:51:28.709526Z'
                    updated_on: '2022-31-03T14:51:28.709526Z'
                  - err_code: 3900
                    err_msg: Verified
                    expires_on: '2022-31-03T14:51:28.709526Z'
                    method: sms
                    state: VERIFIED
                    tried_on: '2022-31-03T14:51:28.709526Z'
                    updated_on: '2022-31-03T14:51:28.709526Z'
                  recipient:
                    phone_number: '11234567890'
                  reference_id: 0123456789ABCDEF0123456789ABCDEF
                  state: VERIFIED
                  updated_on: '2022-31-03T14:51:28.709526Z'
                  verification_policy:
                  - method: whatsapp
                    fallback_time: 30
                  - method: sms
                    fallback_time: 30
        description: ''
      tags:
      - Delivery Reports
    servers:
    - url: https://your-callback-url.com
components:
  schemas:
    DeliveryStatusNotification:
      title: DeliveryStatusNotification
      type: object
      properties:
        status:
          $ref: '#/components/schemas/Status'
        submit_timestamp:
          type: string
          description: An ISO 8601 UTC timestamp indicating when the request was received.
          example: '2016-01-01T01:01:01.010101Z'
        errors:
          type: array
          description: Contains an object for each error that occurred.
          items:
            $ref: '#/components/schemas/Error'
        reference_id:
          type: string
          example: B56259E45884010488343BAA15FB0002
          description: The service's unique identifier for the original transaction this notification is related to.
          minLength: 32
          maxLength: 32
        verify:
          $ref: '#/components/schemas/Verify'
        sub_resource:
          type: string
          example: sms
          description: Indicates which Telesign service processed the original transaction.
        additional_info:
          $ref: '#/components/schemas/AdditionalInfo'
        score_status:
          $ref: '#/components/schemas/ScoreStatus'
      required:
      - status
      - sub_resource
    Verify:
      title: Verify
      type: object
      description: Contains properties related to the status of a verification transaction.
      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.
          example: UNKNOWN
        code_entered:
          description: In some cases, this is the code entered by the end user. Usually the end user's code is not returned, and the value is empty string or `null`.
          type:
          - string
          - 'null'
    Error:
      title: Error
      type: object
      properties:
        code:
          type: integer
          example: -90001
          description: Numeric code that indicates which error occurred.
        description:
          type: string
          example: System Unavailable, Please try again later.
          description: Text that describes this error.
    SIMSwapResponse:
      title: SIMSwapResponse
      type: object
      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
          example: '22:00:00'
          description: 'The time of the SIM swap, if one is detected. '
        risk_indicator:
          type: string
          example: '1'
          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."
        status:
          type: object
          description: Contains properties related to the status of the SIM Swap check.
          properties:
            code:
              type: integer
              example: 2800
              description: A numeric code indicating the processing status for the SIM Swap check.
            description:
              type: string
              description: A short description of the processing status for the SIM Swap check.
              example: Request successfully completed
    Status:
      title: Status
      type: object
      description: Contains properties related to the processing status of this transaction or send.
      properties:
        code:
          type: integer
          example: 200
          description: Numeric code that indicates the processing status of this transaction or send.
        description:
          type: string
          example: Delivered to handset
          description: Text that describes the processing status of this transaction or send.
        updated_on:
          type: string
          example: '2016-10-21T14:05:36.181346Z'
          description: Timestamp that indicates when the status of this transaction or send was last updated.
      required:
      - code
      - description
      - updated_on
    AdditionalInfo:
      title: AdditionalInfo
      type: object
      description: An optional package containing properties with further details about the messaging transaction. The `message_parts_count` and `message_parts_reference_ids` properties only appear if the Message Split feature is enabled for your account. Contact our [Customer Support Team](mailto:support@telesign.com) to request this feature.
      properties:
        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`.
        price:
          type: string
          description: The price from the operator for this transaction.
          example: '0.5112'
        mnc:
          type: string
          description: The mobile network code of the destination operator. See https://en.wikipedia.org/wiki/Mobile_country_code.
          example: '004'
        mcc:
          type: string
          description: The mobile country code of the destination operator. See https://en.wikipedia.org/wiki/Mobile_country_code.
          example: '310'
        currency:
          type: string
          description: The currency type that applies to `price`.
          example: USD
        message_parts_reference_ids:
          type: string
          description: The reference IDs for each part of the longer message, separated by commas.
          example: 35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12
        'sender_id ':
          type: string
          description: The [sender ID](https://support.telesign.com/s/article/What-is-a-Sender-ID) that Telesign used while sending the message. To receive this parameter, ask our [Customer Support Team](mailto:support@telesign.com) to turn on the appropriate feature.
          example: '15558675310'
    ScoreStatus:
      title: ScoreStatus
      type: object
      description: Contains the Intelligence package properties that are returned if Verify Plus and `Send risk recommendation details in transaction response` features are enabled.
      properties:
        phone_type:
          type: object
          description: Contains properties related to phone type.
          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
        risk:
          type: object
          description: Contains properties related to the risk recommendation for the specified phone number.
          properties:
            recommendation:
              type: string
              description: The action that Telesign recommends that you take based on the risk recommendation. Risk Recommendation Scales provides a [table](/enterprise/docs/intelligence-get-started#risk-recommendation-scales) with risk levels.
              example: allow
            score:
              type: integer
              example: 80
              description: The risk recommendation for the current transaction. The risk recommendation will be between 1 and 1000.
            level:
              type: string
              description: The severity of the risk. Risk Recommendation Scales provides a [table](/enterprise/docs/intelligence-get-started#risk-recommendation-scales) with risk levels.
              example: low
        risk_insights:
          type: object
          description: Contains reason code properties with additional information related to the risk recommendation.
          properties:
            status:
              type: integer
              description: The processing status of the risk insights package for the request.
              example: 800
            category:
              type: array
              description: Reason codes related to the category of the phone number, as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings).
              items:
                type: integer
                example: 10010
            a2p:
              type: array
              description: Reason codes specific to application-to-person communication (A2P), as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings). These are automated communications sent to a human, like verification codes, appointment reminders, etc.
              items:
                type: integer
                example: 22103
            p2p:
              type: array
              description: Reason codes specific to person-to-person communication (P2P), as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings). This is two-way communication between two humans, like one friend texting another.
              items:
                type: integer
                example: 30201
            number_type:
              type: array
              description: Reason codes related to the phone number’s type, as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings).
              items:
                type: integer
            ip:
              type: array
              description: Reason codes related to activity of the IP you provided for the phone number, as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings).
              items:
                type: integer
            email:
              type: array
              description: Reason codes related to activity of the email address you provided for the phone number, as described in [Intelligence - Insights reason code mappings](/enterprise/docs/intelligence-insights-reason-code-mappings).
              items:
                type: integer
        numbering:
          type: object
          description: Contains properties related to the numbering attributes of the specified phone number.
          properties:
            phone_number:
              type: string
              description: The base phone number. This is the phone number without the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
              example: '1234567890'
            min_length:
              type: integer
              description: The minimum number of digits allowed for phone numbers with this country dialing code.
              example: 10
            max_length:
              type: integer
              description: The maximum number of digits allowed for phone numbers with this country dialing code.
              example: 10
            country_code:
              type: string
              description: A 1, 2, or 3-digit number representing the [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'
        location:
          type: object
          description: Contains geographical location information associated with the rate center of the phone number when the device was activated. Null is returned when data for a field isn't available for a specific market or country.
          properties:
            city:
              type: string
              description: The city associated with the rate center of the phone number when the device was activated.
              example: Los Angeles
            county:
              type: string
              description: The county (or parish) associated with the rate center of the phone number when the device was activated (U.S. only).
              example: Los Angeles County
            state:
              type: string
              description: The two-letter [state abbreviation code](http://pe.usps.com/text/pub28/28apb.htm) of the state (province, district, or territory) associated with the rate center of the phone number when the device was activated (North America only).
              example: CA
            zip:
              type: string
              description: The five-digit United States Postal Service [ZIP Code](https://www.usps.com/nationalpremieraccounts/findzipcodes.htm) associated with the rate center of the phone number when the device was activated (U.S. only).
              example: '90066'
            country:
              type: object
              description: Contains properties related to the country associated with the rate center of the phone number when the device was activated.
              properties:
                iso2:
                  type: string
                  description: The ISO 3166-1 2-letter [country code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
                  example: US
                iso3:
                  type: string
                  description: ' The ISO 3166-1 3-letter country code associated with the rate center of the phone number when the device was activated.'
                  example: USA
                name:
                  type: string
                  description: The [country name](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes) associated with the rate center of the phone number when the device was activated.
                  example: United States
            timezone:
              type: object
              description: Contains properties related to the time zone associated with the rate center of the phone number when the device was activated. For maximum and minimum UTC offsets, they are specified in units of hours, and range from -12 to +14. For positive numbers, the plus sign (+) may not be returned. Additional offsets due to Daylight Savings Time or Summer Time are not considered. For example, Russia, which spans 11 time zones, has a minimum UTC offset of +2, and a maximum of +12.
              properties:
                name:
                  type: string
                  description: The time zone associated with the rate center of the phone number when the device was activated (U.S. only).
                  example: America/Los Angeles
                utc_offset_max:
                  type: string
                  description: ' For international phone numbers, this parameter returns the maximum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the same result as utc_offset_min.'
                  example: '-8'
                utc_offset_min:
                  type: string
                  description: For international phone numbers, this parameter returns the minimum UTC offset for the country associated with the rate center of the phone number when the device was activated. For U.S. phone numbers, this parameter returns the UTC offset associated with the rate center of the phone number when the device was activated.
                  example: '-8'
            coordinates:
              type: object
              description: Contains properties with details about the geographical coordinates of the location where the phone number is registered.
              properties:
                latitude:
                  type: number
                  format: float
                  description: Latitude specifies the North-South position of a point on the Earth’s surface. It is an angular measurement that ranges from 0° at the Equator, to 90° at the North Pole (and -90° at the South Pole). It is returned here as a value indicating the number of degrees of latitude of the location associated with the phone number, expressed in seven decimal digits, with five decimal places.
                  example: 33.99791
                longitude:
                  type: number
                  format: float
                  description: Longitude specifies the East-West position of a point on the Earth’s surface. It is an angle measured East or West from the [prime meridian](https://en.wikipedia.org/wiki/Prime_meridian) —ranging from 0° at the prime meridian, to +180° Eastward and -180° Westward. It is returned here as a value indicating the number of degrees of longitude of the location associated with the phone number, expressed in eight decimal digits, with five decimal places.
                  example: -118.42302
            metro_code:
              type: string
              description: A 4-digit string indicating the Primary Metropolitan Statistical Area (PMSA) code for the location associated with the rate center of the phone number when the device was activated (U.S. only). PMSA Codes are governed by the [US Census Bureau](http://www.census.gov/). This information is useful for large metropolitan areas that comprise several smaller cities. For example, the PMSA for Long Beach, California is Los Angeles County, which gives Long Beach the PMSA Code 4480.
              example: '4480'
        blocklisting:
          type: object
          description: Contains details about whether the number was blocked and who requested the block.
          properties:
            block_code:
              type: integer
              description: A code indicating whether the number is blocked, and who blocked it. `0` for not blocked, `1` for blocked by TeleSign, `2` for block requested by your organization, `3` for block requested by your account or set by TeleSign on behalf of your account, and `4` if the block state is unknown.
              example: 0
            block_description:
              type: string
              description: Text explaining the block status.
              example: Not blocked
            blocked:
              type: boolean
              description: If `true`, this number is blocked. If `false`, this number is not blocked.
        carrier:
          type: object
          description: Contains details about the company that provides telecommunications services for this phone number. Behavior of this property, including information returned for ported phone numbers, can vary depending on the country of the phone number. See [How does carrier data vary by country?](https://support.telesign.com/s/article/How-does-carrier-data-vary-by-country) for more details.
          properties:
            carrier_id:
              type: integer
              description: An ID specifying this carrier.
              example: 309
            name:
              type: string
              description: The name of this carrier.
              example: AT&T Wireless
    DeliveryStatusNotification_2:
      title: DeliveryStatusNotification
      type: object
      properties:
        created_on:
          type: string
          example: '2022-31-03T14:51:28.709526Z'
          description: A timestamp that indicates when Telesign created this verification process.
        inner_methods:
          type: array
          items:
            $ref: '#/components/schemas/InnerVerificationMethodStatus'
        recipient:
          $ref: '#/components/schemas/VerificationRecipient'
        reference_id:
          type: string
          description: A unique, randomly generated hex value that identifies this verification process.
          minLength: 32
          maxLength: 32
          example: 0123456789ABCDEF0123456789ABCDEF
        state:
          type: string
          description: The current state of this verification process.
          enum:
          - CREATED
          - ONGOING
          - REJECTED
          - FAILED
          - VERIFIED
          - CANCELED
          example: ONGOING
        updated_on:
          type: string
          description: 'An [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp indicating when the status of this verification process was last updated. '
          example: '2022-31-03T14:51:28.709526Z'
        verification_policy:
          $ref: '#/components/schemas/VerificationPolicy'
      required:
      - state
    InnerVerificationMethodStatus:
      title: Status of inner verification method
      description: Contains properties related to the processing status of the specified inner verification method. One verification process can include multiple inner verification methods.
      type: object
      properties:
        method:
          $ref: '#/components/schemas/VerificationMethod'
        state:
          type: string
          description: Text describing the processing status of the specified verification method. This is not the same as the overall status of the verification process.
          enum:
          - CREATED
          - ONGOING
          - SKIPPED
          - REJECTED
          - FAILED
          - VERIFIED
          - CANCELED
          example: ONGOING
        err_code:
          type: integer
          description: A numeric code indicating which error occured while attempting to use this verification method.
          example: 2
        err_msg:
          type: string
          description: Text describing the error that occured while attempting to use this verification method.
          example: MSG_NOT_DELIVERED
        tried_on:
          type: string
          description: A timestamp that indicates when this verification method was attempted.
          example: '2022-31-03T14:51:28.709526Z'
        updated_on:
          type: string
          description: An [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp that indicates when the state of attempting verification with this method was last updated.
          example: '2022-31-03T14:51:28.709526Z'
      required:
      - method
    VerificationMethod:
      title: Verification Method
      description: One of the [verification methods](/enterprise/docs/verify-api-get-started#supported-verification-methods) included in a verification policy. Each method employs a Telesign service, such as Silent Verify or Push Verify.
      type: string
      enum:
      - silent
      - sms
      - push
      - rcs
      - whatsapp
      - email
      example: sms
    VerificationPolicy:
      title: Verification Policy
      description: An ordered set of verification methods and their fallback times that the Verify API uses for this verification process. See [verification policy](/enterprise/docs/verify-api-verification-policy-and-fallback-time) for more details.
      type: array
      minItems: 1
      example:
      - method: silent
        fallback_time: 15
      - method: sms
        fallback_time: 15
      items:
        type: object
        properties:
          method:
            $ref: '#/components/schemas/VerificationMethod'
          fallback_time:
            type: integer
            description: The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method specified in the active [verification policy](/enterprise/docs/verify-api-verification-policy-and-fallback-time). It is possible for the failover to happen earlier if certain failure conditions occur.
            example: 10
    VerificationRecipient:
      title: Verification Recipient
      description: Contains properties with the recipient identifier for a [verification process](/enterprise/docs/verify-api-get-started#key-terms).
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        phone_number:
          type: string
          description: The recipient's phone number, as digits without spaces or special characters, beginning with the [country dialing code](/enterprise/docs/codes-languages-and-time-zones#country-codes-and-dialing-codes).
          example: '11234567890'
        push_app_token:
          type: string
          example: 23324n2b42i:fbo234cu2435n53ng_f4i2bdf2o4i6n53bh_234ol5436b735v462g3c42gc34b24j6b345
          description: Identifies the instance of your mobile application installed on the user's mobile device. This is also called a "registration token" in Firebase Cloud Messaging or a "device token" in iOS. This is required when using the Push Verify verification method.
        email:
          type: string
          description: The recipient's email address.
          example: ncarolina@vero-finto.com
    DeliveryStatusNotification_3:
      title: DeliveryStatusNotification
      type: object
      properties:
        created_on:
          type: string
          example: '2022-31-03T14:51:28.709526Z'
          description: A timestamp that indicates when Telesign created this verification process.
        inner_methods:
          type: array
          items:
            $ref: '#/components/schemas/InnerVerificationMethodStatus'
        recipient:
          $ref: '#/components/schemas/VerificationRecipient'
        reference_id:
          type: string
          description: A unique, randomly generated hex value that identifies this verification process.
          minLength: 32
          maxLength: 32
          example: 0123456789ABCDEF0123456789ABCDEF
        state:
          type: string
          description: The current state of this verification process.
          enum:
          - CREATED
          - ONGOING
          - REJECTED
          - FAILED
          - VERIFIED
          - CANCELED
          example: ONGOING
        updated_on:
          type: string
          description: 'An [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp indicating when the status of this verification process was last updated. '
          example: '2022-31-03T14:51:28.709526Z'
        verification_policy:
          $ref: '#/components/schemas/VerificationPolicy'
      required:
      - state
x-refined-from:
- telesign-sms-verify-api-callbacks-openapi.json
- telesign-verify-api-callbacks-openapi.json
- telesign-sms-verify-api-callbacks-openapi.yml
- telesign-verify-api-callbacks-openapi.yml
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true