openapi: 3.0.0
servers:
  - url: https://api.nexmo.com/conversions
info:
  contact:
    email: devrel@nexmo.com
    name: Nexmo.com
    url: https://developer.nexmo.com/
    x-twitter: Nexmo
  description: |-
    The Conversion API allows you to tell Nexmo about the reliability of your 2FA communications. Sending conversion data back to us means that Nexmo can deliver messages faster and more reliably.
    The conversion data you send us is confidential: Nexmo does not share it with third parties.
    In order to identify the carriers who provide the best performance, Nexmo continually tests the routes we use to deliver SMS and voice calls. Using Adaptive Routing™, Nexmo actively reroutes messages through different carrier routes and ensures faster and more reliable delivery for your messages. The route choice is made using millions of real-time conversion data points.
  license:
    name: The MIT License (MIT)
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.nexmo.com/terms-of-use
  title: Nexmo Conversion API
  version: 1.0.1
  x-apiClientRegistration: https://dashboard.nexmo.com/sign-up
  x-logo:
    url: https://www.vonage.com/content/dam/vonage/us-en/api/illustrations/Mobile_APIs_Services.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/conversion.yml
      version: "3.0"
  x-providerName: nexmo.com
  x-serviceName: conversion
externalDocs:
  url: https://developer.nexmo.com/api/conversion
  x-sha1: 8ad8bc6b0c51af4ca458c13cfced6124783ab113
security:
  - apiKey: []
    apiSecret: []
  - apiKey: []
    apiSig: []
tags:
  - description: SMS Conversion Request
    name: SMS Conversion
  - description: Voice Conversion Request
    name: Voice Conversion
paths:
  /sms:
    post:
      description: Send a Conversion API request with information about the SMS message identified by `message-id`. Nexmo uses your conversion data and internal information about `message-id` to help improve our routing of messages in the future.
      operationId: smsConversion
      parameters:
        - $ref: "#/components/parameters/message-id"
        - $ref: "#/components/parameters/delivered"
        - $ref: "#/components/parameters/timestamp"
      responses:
        "200":
          description: OK
        "401":
          description: Wrong credentials
        "402":
          description: Conversion has not been enabled for your account
        "420":
          description: Invalid parameters
        "423":
          description: Invalid parameters
      summary: Tell Nexmo if your SMS message was successful
      tags:
        - SMS Conversion
  /voice:
    post:
      description: Send a Conversion API request with information about the Call or Text-To-Speech identified by `message-id`. Nexmo uses your conversion data and internal information about `message-id` to help improve our routing of messages in the future.
      operationId: voiceConversion
      parameters:
        - $ref: "#/components/parameters/message-id"
        - $ref: "#/components/parameters/delivered"
        - $ref: "#/components/parameters/timestamp"
      responses:
        "200":
          description: OK
        "401":
          description: Wrong credentials
        "402":
          description: Conversion has not been enabled for your account
        "420":
          description: Invalid parameters
        "423":
          description: Invalid parameters
      summary: Tell Nexmo if your voice call was successful
      tags:
        - Voice Conversion
components:
  parameters:
    delivered:
      description: |-
        Set to _true_ if your user replied to the message you sent. Otherwise, set to _false_.
        **Note**: for curl, use 0 and 1.
      example: true
      in: query
      name: delivered
      required: true
      schema:
        enum:
          - true
          - false
          - 0
          - 1
    message-id:
      description: The ID you receive in the response to a request. * From the Verify API - use the `event_id` in the response to Verify Check. * From the SMS API - use the `message-id` * From the Text-To-Speech API - use the `call-id` * From the Text-To-Speech-Prompt API - use the `call-id`
      example: 00A0B0C0
      in: query
      name: message-id
      required: true
      schema:
        type: string
    timestamp:
      description: |-
        When the user completed your call-to-action (e.g. visited your website, installed your app) in [UTC±00:00](https://en.wikipedia.org/wiki/UTC%C2%B100:00) format: _yyyy-MM-dd HH:mm:ss_.
        If you do not set this parameter, Nexmo uses the time it receives this request.
      example: 2020-01-01 12:00:00
      in: query
      name: timestamp
      required: true
      schema:
        type: string
  securitySchemes:
    apiKey:
      description: You can find your API key in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_key
      type: apiKey
    apiSecret:
      description: You can find your API secret in your [account overview](https://dashboard.nexmo.com/account-overview)
      in: query
      name: api_secret
      type: apiKey
    apiSig:
      description: "The hash of the request parameters in alphabetical order, a timestamp and the signature secret. For example: `sig=SIGNATURE`"
      in: query
      name: sig
      type: apiKey
