ding.yaml

openapi: 3.1.0
security:
  - APIKey: []
info:
  title: Ding
  version: 1.0.0
  description: "The OTP API allows you to send authentication codes to your users using their phone numbers. The V1 API is **deprecated**. Technical support will end by **October 2025** and will be **removed by April 2026**. No new features and functionality will be added to the V1 API."
  contact:
    email: support@prelude.so
servers:
  - url: "https://api.ding.live/v1"
    description: The production Ding API server
tags:
  - name: OTP
    description: Send OTP codes to your users using their phone numbers.
  - name: Lookup
    description: Retrieve up-to-date metadata about a specific phone number
paths:
  /authentication:
    post:
      deprecated: true
      description: Send an OTP code to a user's phone number.
      x-speakeasy-usage-example:
        title: Send a code
        description: Send an OTP code to a user's phone number.
        position: 1
      summary: Send a code
      tags:
        - OTP
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAuthenticationResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: create-authentication
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAuthenticationRequest"
  /check:
    post:
      deprecated: true
      description: Check that a code entered by a user is valid.
      x-speakeasy-usage-example:
        title: Check a code
        description: Check that a code entered by a user is valid.
        position: 2
      summary: Check a code
      tags:
        - OTP
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateCheckResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: check
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCheckRequest"
  /authentication/feedback:
    post:
      deprecated: true
      description: Send feedback about the authentication process.
      x-speakeasy-usage-example:
        title: Send feedback
        description: |
          Send feedback about the authentication process.
        position: 4
      summary: Send feedback
      tags:
        - OTP
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: feedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackRequest"
  /authentication/{auth_uuid}:
    get:
      deprecated: true
      description: Get the status of an authentication.
      x-speakeasy-usage-example:
        title: Get authentication status
        description: Get the status of an authentication.
        position: 5
      summary: Get authentication status
      tags:
        - OTP
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthenticationStatusResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: getAuthenticationStatus
      parameters:
        - in: path
          name: auth_uuid
          required: true
          schema:
            type: string
            format: uuid
            description: The UUID of the authentication.
  /retry:
    post:
      deprecated: true
      description: Perform a retry if a user has not received the code.
      x-speakeasy-usage-example:
        title: Perform a retry
        description: Perform a retry if a user has not received the code.
        position: 3
      summary: Perform a retry
      tags:
        - OTP
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetryAuthenticationResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: retry
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetryAuthenticationRequest"
  /lookup/{phone_number}:
    get:
      deprecated: true
      description: Perform a phone number lookup.
      x-speakeasy-usage-example:
        title: Look up for phone number
        description: Perform a phone number lookup.
        position: 6
      summary: Look up for phone number
      tags:
        - Lookup
      parameters:
        - in: header
          name: customer-uuid
          schema:
            type: string
            format: uuid
            description: Your customer UUID, which can be found in the API settings in the dashboard.
          required: true
        - in: query
          name: type
          schema:
            type: array
            format: string
            items:
              type: string
              enum:
                - cnam
            description: >
              Optional features. Possible values are:
                * `cnam` - Retrieve CNAM (Caller ID Name) along with other information. Contact us if you need to use this functionality.
        - in: path
          name: phone_number
          required: true
          schema:
            type: string
            format: phone_number
            description: An E.164 formatted phone number to look up.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LookupResponse"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
      operationId: lookup
components:
  schemas:
    FeedbackRequest:
      type: object
      required:
        - customer_uuid
        - phone_number
        - status
      properties:
        customer_uuid:
          type: string
          format: uuid
          description: Your customer UUID, which can be found in the API settings in the dashboard.
        phone_number:
          type: string
          format: phone_number
          examples: ["+1234567890"]
          description: An E.164 formatted phone number.
        status:
          type: string
          examples: ["onboarded"]
          description: The type of the feedback.
          enum:
            - onboarded
            - not_onboarded
    FeedbackResponse:
      type: object
      properties:
        uuid:
          type: string
          examples: ["123e4567-e89b-12d3-a456-4266141740a0"]
          description: The UUID of the feedback.
    CheckStatus:
      type: string
      examples: ["valid"]
      description: >
        The status of the check. Possible values are:
          * `unknown` - The status is unknown.
          * `valid` - The code is valid.
          * `invalid` - The code is invalid.
          * `without_attempt` - No attempt was sent yet, so a check cannot be completed.
          * `rate_limited` - The authentication was rate limited and cannot be checked.
          * `already_validated` - The authentication has already been validated.
          * `expired_auth` - The authentication has expired and cannot be checked.
      enum:
        - unknown
        - valid
        - invalid
        - without_attempt
        - rate_limited
        - already_validated
        - expired_auth
    AuthenticationStatusEventResponse:
      type: object
      properties:
        type:
          type: string
          description: The type of the event.
          enum:
            - attempt
            - check
            - delivery_status
            - balance_update
        created_at:
          type: string
          format: date-time
    AuthenticationStatusResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: The UUID of the corresponding authentication.
        phone_number:
          type: string
          format: phone_number
          examples: ["+1234567890"]
          description: An E.164 formatted phone number.
        template_id:
          type: string
          description: The template id associated with the message content variant to be sent.
        correlation_id:
          type: string
          description: A unique, user-defined identifier that will be included in webhook events.
        created_at:
          type: string
          format: date-time
        signals:
          type: object
          description: "Signals are data points used to distinguish between fraudulent and legitimate users."
          properties:
            ip:
              type: string
              format: ipv4
              description: The IP address of the user's device.
            device_id:
              type: string
              description: Unique identifier for the user's device. For Android, this corresponds to the `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
            device_type:
              type: string
              enum:
                - ANDROID
                - IOS
                - IPADOS
                - TVOS
                - WEB
              description: The type of device the user is using.
            app_version:
              type: string
              description: The version of your application.
            app_realm:
              type: string
              description: The Android SMS Retriever API hash code that identifies your app.
                This allows you to automatically retrieve and fill the OTP code on Android devices.
            os_version:
              type: string
              description: The version of the user's device operating system.
            device_model:
              type: string
              description: The model of the user's device.
            is_returning_user:
              type: boolean
              description: This signal should do more than just confirm if a user is returning to your app; it should provide a higher level of trust, indicating that the user is genuine. For more details, refer to [Signals](/verify/v2/documentation/prevent-fraud#signals).
        events:
          type: array
          description: Represents a collection of events that occur during the authentication process. Each event captures specific actions and outcomes related to the authentication attempts, checks, delivery statuses, and balance updates. The array can contain different types of events, each with its own structure and properties.
          items:
            anyOf:
              - title: Attempt
                allOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        description: The ID of the attempt.
                      content:
                        type: string
                        description: The content of the attempt.
                        examples: ["Your code is 123456"]
                      sender_id:
                        type: string
                        description: The sender ID of the attempt.
                      capability:
                        type: string
                        description: The capability of the attempt.
                        enum:
                          - rcs
                          - text
                          - whatsapp
                          - viber
                          - zalo
                          - telegram
                      attempt_number:
                        type: integer
                        description: The attempt number.
                      status:
                        type: string
                        enum:
                          - pending
                          - delivered
                          - failed
                          - rate_limited
                          - expired
                        description: >
                          The status of the attempt. Possible values are:
                            * `pending` - The attempt is pending.
                            * `delivered` - The attempt was delivered.
                            * `failed` - The attempt failed.
                            * `rate_limited` - The authentication was rate limited and cannot be retried.
                            * `expired` - The authentication has expired and cannot be retried.
                  - $ref: "#/components/schemas/AuthenticationStatusEventResponse"
              - title: Check
                allOf:
                  - type: object
                    properties:
                      id:
                        type: string
                        description: The ID of the check.
                      code:
                        type: string
                        description: The code that was checked.
                        examples: ["123456"]
                      status:
                        allOf:
                          - $ref: "#/components/schemas/CheckStatus"
                  - $ref: "#/components/schemas/AuthenticationStatusEventResponse"
              - title: Delivery Status
                allOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - unknown
                          - submitted
                          - in_transit
                          - delivered
                          - undeliverable
                        description: >
                          The status of the delivery. Possible values are:
                            * `unknown` - The status of the delivery is unknown.
                            * `submitted` - The message has been submitted to the carrier.
                            * `in_transit` - The message is in transit to the recipient.
                            * `delivered` - The message has been delivered to the recipient.
                            * `undeliverable` - The message could not be delivered to the recipient.
                      attempt_id:
                        type: string
                        description: The ID of the attempt.
                      attempt_number:
                        type: integer
                        description: The attempt number.
                      originated_at:
                        type: string
                        format: date-time
                        description: The date and time from the provider.
                  - $ref: "#/components/schemas/AuthenticationStatusEventResponse"
              - title: Balance Update
                allOf:
                  - type: object
                    properties:
                      balance_update_type:
                        type: string
                        enum:
                          - unknown
                          - authentication
                          - attempt
                          - attempt_pending
                          - attempt_success
                          - authentication_pending
                          - authentication_success
                      amount:
                        type: number
                        format: double
                        description: The amount of the balance update.
                  - $ref: "#/components/schemas/AuthenticationStatusEventResponse"

    LookupResponse:
      type: object
      properties:
        phone_number:
          type: string
          format: phone_number
          examples: ["+1234567890"]
          description: An E.164 formatted phone number.
        mcc:
          type: string
          examples: ["310"]
          description: The mobile country code of the phone number.
        mnc:
          type: string
          examples: ["410"]
          description: The mobile network code of the phone number.
        caller_name:
          type: string
          description: The CNAM (Caller ID Name) associated with the phone number. Contact us if you need to use this functionality. Once enabled, put `cnam` option to `type` query parameter.
        carrier:
          type: string
          examples: ["AT&T"]
          description: The carrier of the phone number.
        country_code:
          type: string
          examples: ["US"]
          description: The ISO 3166-1 alpha-2 country code of the phone number.
        number_ported:
          type: boolean
          description: Whether the phone number has been ported.
        temporary_phone_number:
          type: boolean
          description: Whether the phone number is in our database of disposable, temporary phone numbers
        line_type:
          type: string
          examples: ["Mobile"]
          enum:
            - CallingCards
            - FixedLine
            - InternetServiceProvider
            - LocalRate
            - Mobile
            - Other
            - Pager
            - PayPhone
            - PremiumRate
            - Satellite
            - Service
            - SharedCost
            - ShortCodesCommercial
            - TollFree
            - UniversalAccess
            - Unknown
            - VPN
            - VoiceMail
            - Voip
          description: >
            The type of phone line.
              * `CallingCards` - Numbers that are associated with providers of pre-paid domestic and international calling cards.
              * `FixedLine` - Landline phone numbers.
              * `InternetServiceProvider` - Numbers reserved for ISPs.
              * `LocalRate` - Numbers that can be assigned non-geographically.
              * `Mobile` - Mobile phone numbers.
              * `Other` - Other types of services.
              * `Pager` - Number ranges specifically allocated to paging devices.
              * `PayPhone` - Allocated numbers for payphone kiosks in some countries.
              * `PremiumRate` - Landline numbers where the calling party pays more than standard.
              * `Satellite` - Satellite phone numbers.
              * `Service` - Automated applications.
              * `SharedCost` - Specific landline ranges where the cost of making the call is shared between the calling and called party.
              * `ShortCodesCommercial` - Short codes are memorable, easy-to-use numbers, like the UK's NHS 111, often sold to businesses. Not available in all countries.
              * `TollFree` - Number where the called party pays for the cost of the call not the calling party.
              * `UniversalAccess` - Number ranges reserved for Universal Access initiatives.
              * `Unknown` - Unknown phone number type.
              * `VPN` - Numbers are used exclusively within a private telecommunications network, connecting the operator's terminals internally and not accessible via the public telephone network.
              * `VoiceMail` - A specific category of Interactive Voice Response (IVR) services.
              * `Voip` - Specific ranges for providers of VoIP services to allow incoming calls from the regular telephony network.
    RetryAuthenticationResponse:
      type: object
      properties:
        authentication_uuid:
          type: string
          format: uuid
          description: The UUID of the corresponding authentication.
        status:
          type: string
          description: >
            The status of the retry. Possible values are:
              * `approved` - The retry was approved and a new code was sent.
              * `denied` - The retry was denied.
              * `no_attempt` - No attempt was sent yet, so a retry cannot be completed.
              * `rate_limited` - The authentication was rate limited and cannot be retried.
              * `expired_auth` - The authentication has expired and cannot be retried.
              * `already_validated` - The authentication has already been validated.
          examples: ["approved"]
          enum:
            - approved
            - denied
            - no_attempt
            - rate_limited
            - expired_auth
            - already_validated
        created_at:
          type: string
          format: date-time
        next_retry_at:
          type: string
          format: date-time
          description: The time at which the next retry will be available.
        remaining_retry:
          type: integer
          minimum: 0
          examples: [3]
          description: The number of remaining retries.
    RetryAuthenticationRequest:
      type: object
      required:
        - customer_uuid
        - authentication_uuid
      properties:
        customer_uuid:
          type: string
          format: uuid
          description: Your customer UUID, which can be found in the API settings in the dashboard.
        authentication_uuid:
          type: string
          format: uuid
          description: The authentication UUID that was returned when you created the authentication.

    CreateCheckResponse:
      type: object
      properties:
        authentication_uuid:
          type: string
          format: uuid
          description: The UUID of the corresponding authentication.
        status:
          allOf:
            - $ref: "#/components/schemas/CheckStatus"
    CreateCheckRequest:
      type: object
      required:
        - customer_uuid
        - authentication_uuid
        - check_code
      properties:
        customer_uuid:
          type: string
          format: uuid
          description: Your customer UUID, which can be found in the API settings in the Dashboard.
        authentication_uuid:
          type: string
          format: uuid
          description: The authentication UUID that was returned when you created the authentication.
        check_code:
          type: string
          examples: ["123456"]
          description: The code that the user entered.
    CreateAuthenticationRequest:
      type: object
      required:
        - customer_uuid
        - phone_number
      properties:
        customer_uuid:
          type: string
          format: uuid
          description: Your customer UUID, which can be found in the API settings in the dashboard.
        phone_number:
          type: string
          format: phone_number
          examples: ["+1234567890"]
          description: An E.164 formatted phone number to send the OTP to.
        ip:
          type: string
          format: ipv4
          description: The IP address of the user's device.
        device_id:
          type: string
          description: Unique identifier for the user's device. For Android, this corresponds to the `ANDROID_ID` and for iOS, this corresponds to the `identifierForVendor`.
        device_type:
          type: string
          enum:
            - IOS
            - ANDROID
            - WEB
          description: The type of device the user is using.
        app_version:
          type: string
          description: The version of your application.
        sender_id:
          type: string
          description: The Sender ID to use when sending the message.
        callback_url:
          type: string
          format: url
          description: A webhook URL to which delivery statuses will be sent.
        app_realm:
          type: string
          description: The Android SMS Retriever API hash code that identifies your app.
            This allows you to automatically retrieve and fill the OTP code on Android devices.
        os_version:
          type: string
          description: The version of the user's device operating system.
        device_model:
          type: string
          description: The model of the user's device.
        is_returning_user:
          type: boolean
          description: This signal should do more than just confirm if a user is returning to your app; it should provide a higher level of trust, indicating that the user is genuine.
        template_id:
          type: string
          description: The template id associated with the message content variant to be sent.
        correlation_id:
          type: string
          description: A unique, user-defined identifier that will be included in webhook events
        locale:
          type: string
          format: BCP-47
          examples: ["en-US", "el-GR", "fr-FR"]
          description: A BCP-47 locale indicating the language the SMS should be sent to; if this is not set, the SMS will be sent to the language specified by the country code of the message. If we don't support the language set, the message will be sent in US English (en-US).
    CreateAuthenticationResponse:
      type: object
      description: A successful response to an authentication creation request.
      properties:
        authentication_uuid:
          type: string
          format: uuid
          description: A unique identifier for the authentication that you can use on the /check and /retry endpoints.
        status:
          type: string
          description: >
            The status of the authentication. Possible values are:
              * `pending` - The OTP code is being sent.
              * `rate_limited` - This user is rate-limited and cannot receive another code.
              * `spam_detected` - This attempt is flagged as spam. Go to the dashboard for more details.
          enum:
            - pending
            - rate_limited
            - spam_detected
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: The time at which the authentication expires and can no longer be checked or retried.
    # -------------------------------------------------------------------------
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          examples: ["invalid_phone_number"]
          description: A machine-readable code that describes the error.
          enum:
            - account_invalid
            - app_realm_require_device_type
            - bad_request
            - blocked_number
            - duplicated_feedback_status
            - internal_server_error
            - invalid_app_realm
            - invalid_app_version
            - invalid_auth_uuid
            - invalid_device_id
            - invalid_device_model
            - invalid_feedback_status
            - invalid_line
            - invalid_os_version
            - invalid_phone_number
            - invalid_sender_id
            - invalid_template_id
            - negative_balance
            - no_associated_auth_found
            - suspended_account
            - unauthorized_sender_id
            - unsupported_app_realm_device_type
            - unsupported_region
        message:
          type: string
          examples: ["+0 is not a valid phone number"]
          description: A human-readable message that describes the error.
        doc_url:
          type: string
          description: A link to the documentation that describes the error.
          examples: ["https://docs.prelude.so/verify/v1/documentation/errors#invalid_phone_number"]
  securitySchemes:
    APIKey:
      name: x-api-key
      type: apiKey
      in: header
      x-speakeasy-example: YOUR_API_KEY