Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@tbedford @mheap
611 lines (610 sloc) 20.3 KB
openapi: 3.0.0
info:
title: Nexmo Message Search API
version: 1.0.2
description: >-
The Messages API lets you retrieve messages you have sent via the SMS API by
ID, as well as retrieve details of messages that were rejected.
contact:
name: Nexmo.com
email: devrel@nexmo.com
url: 'https://developer.nexmo.com/'
x-twitter: Nexmo
termsOfService: 'https://www.nexmo.com/terms-of-use'
license:
name: The MIT License (MIT)
url: 'https://opensource.org/licenses/MIT'
x-logo:
url: 'https://twitter.com/Nexmo/profile_image?size=original'
x-apiClientRegistration: 'https://dashboard.nexmo.com/sign-up'
servers:
- url: 'https://rest.nexmo.com/search'
externalDocs:
url: 'https://developer.nexmo.com/api/developer/messages'
x-sha1: d8836c374e2a7504bd2cd59e05fcee440f67cb44
security:
- apiKey: []
apiSecret: []
paths:
/message:
get:
summary: Get a single message
description: >-
Retrieve information about a single message that you sent using SMS API
or that was received on your number.
operationId: searchMessage
parameters:
- name: id
in: query
required: true
description: The ID of the message you want to retrieve.
example: 00A0B0C0
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/messageBase'
- $ref: '#/components/schemas/messageMT'
application/xml:
schema:
oneOf:
- $ref: '#/components/schemas/messageBase'
- $ref: '#/components/schemas/messageMT'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorJson'
application/xml:
schema:
$ref: '#/components/schemas/errorXml'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
application/xml:
schema:
$ref: '#/components/schemas/error'
/messages:
get:
summary: Search messages
description: >-
Retrieve multiple messages that you sent using the SMS API or that were received
on your number. You may provide one or more `ids` are specified, or both `date` and `number`
to identify the messages.
operationId: searchMessages
parameters:
- name: ids
in: query
description: A message ID to search for. You can specify up to 10 message IDs to search for as query parameters.
example: 'ids=123456789&ids=987654321'
schema:
type: string
- name: date
in: query
description: >-
The date the request to SMS API was submitted in the following
format: `YYYY-MM-DD`
example: '2020-01-01'
schema:
type: string
format: date
- name: to
in: query
description: The phone number the message was sent to.
example: '447700900000'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
application/xml:
schema:
$ref: '#/components/schemas/messages'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorJson'
application/xml:
schema:
$ref: '#/components/schemas/errorXml'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
application/xml:
schema:
$ref: '#/components/schemas/error'
/rejections:
get:
summary: Search for rejections
description: >-
Search for messages that have been rejected by Nexmo. Messages rejected
by the carrier do not appear.
operationId: searchRejections
parameters:
- name: date
in: query
description: >-
The date the request to SMS API was submitted in the following
format: `YYYY-MM-DD`
required: true
example: '2020-01-01'
schema:
type: string
format: date
- name: to
in: query
description: The phone number the message was sent to.
required: true
example: '447700900000'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/rejections'
application/xml:
schema:
$ref: '#/components/schemas/rejections'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/errorJson'
application/xml:
schema:
$ref: '#/components/schemas/errorXml'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
application/xml:
schema:
$ref: '#/components/schemas/error'
components:
schemas:
messageBase:
type: object
description: Inbound (MO)
required:
- type
- message-id
- account-id
- network
- from
- to
- body
- date-received
xml:
name: message
properties:
type:
type: string
description: >-
The message type. `MT` (mobile terminated or outbound) or `MO`
(mobile originated or inbound)
example: MO
enum:
- MO
message-id:
type: string
description: The id of the message you sent.
example: 0A00000000ABCD00
account-id:
type: string
description: Your API Key.
example: API_KEY
date-received:
type: string
description: >-
The date and time at UTC+0 when Platform received your request in
the following format: `YYYY-MM-DD HH:MM:SS`.
example: '2020-01-01 12:00:00'
network:
type: string
description: >-
The [MCCMNC](https://en.wikipedia.org/wiki/Mobile_Network_Code) for
the carrier who delivered the message.
example: '012345'
from:
type: string
description: >-
The sender ID the message was sent from. Could be a phone number or
name.
example: Nexmo
to:
type: string
description: The phone number the message was sent to.
example: 447700900000
body:
type: string
description: The body of the message.
example: A text message sent using the Nexmo SMS API
messageMT:
description: Outbound (MT)
type: object
required:
- type
- message-id
- account-id
- network
- from
- to
- body
- date-received
- price
- final-status
- date-closed
- latency
xml:
name: message
properties:
type:
type: string
description: >-
The message type. `MT` (mobile terminated or outbound) or `MO`
(mobile originated or inbound)
example: MT
enum:
- MT
message-id:
$ref: '#/components/schemas/messageBase/properties/message-id'
account-id:
$ref: '#/components/schemas/messageBase/properties/account-id'
network:
$ref: '#/components/schemas/messageBase/properties/network'
from:
$ref: '#/components/schemas/messageBase/properties/from'
to:
$ref: '#/components/schemas/messageBase/properties/to'
body:
$ref: '#/components/schemas/messageBase/properties/body'
date-received:
$ref: '#/components/schemas/messageBase/properties/date-received'
price:
type: number
description: Price in Euros for a MT message.
example: 0.0333
date-closed:
type: string
description: >-
The date and time at UTC+0 when Platform received the delivery
receipt from the carrier who delivered the MT message. This
parameter is in the following format `YYYY-MM-DD HH:MM:SS`.
format: date-time
example: '2020-01-01 12:00:00'
latency:
type: number
description: >-
The overall latency between `date-received` and `date-closed` in
milliseconds.
example: 3000
client-ref:
type: string
maxLength: 40
description: >-
The [internal
reference](https://developer.nexmo.com/api/sms#send-an-sms) you set
in the request.
example: my-personal-reference
status:
type: string
description: >-
A code that explains where the message is in the delivery process.
If status is not `delivered` check `error-code` for more
information. If status is `accepted` ignore the value of
`error-code`.
enum:
- delivered
- expired
- failed
- rejected
- accepted
- buffered
- unknown
x-ms-enum:
name: status
values:
- value: delivered
description: This message has been delivered to the phone number.
- value: expired
description: >-
The target carrier did not send a status in the 48 hours after
this message was delivered to them.
- value: failed
description: The target carrier failed to deliver this message.
- value: rejected
description: The target carrier rejected this message.
- value: accepted
description: The target carrier has accepted to send this message.
- value: buffered
description: This message is in the process of being delivered.
- value: unknown
description: The target carrier has returned an undocumented status code.
final-status:
type: string
description: The status of `message-id` at `date-closed`.
enum:
- DELIVRD
- EXPIRED
- UNDELIV
- REJECTD
- UNKNOWN
x-ms-enum:
name: final-status
values:
- value: DELIVRD
description: This message has been delivered to the phone number.
- value: EXPIRED
description: >-
The target carrier did not send a status in the 48 hours after
this message was delivered to them.
- value: UNDELIV
description: The target carrier failed to deliver this message.
- value: REJECTD
description: The target carrier rejected this message.
- value: UNKNOWN
description: The target carrier has returned an undocumented status code.
example: DELIVRD
error-code:
$ref: '#/components/schemas/error-code'
error-code-label:
$ref: '#/components/schemas/error-code-label'
messages:
type: object
properties:
count:
type: integer
description: The number of messages included in the response.
items:
type: array
description: The messages in the response.
xml:
wrapped: true
items:
type: object
xml:
name: message
oneOf:
- $ref: '#/components/schemas/messageBase'
- $ref: '#/components/schemas/messageMT'
rejections:
type: object
properties:
count:
type: integer
description: The number of messages included in the response.
items:
type: array
xml:
wrapped: true
items:
type: object
properties:
account-id:
$ref: '#/components/schemas/messageBase/properties/account-id'
from:
$ref: '#/components/schemas/messageBase/properties/from'
to:
$ref: '#/components/schemas/messageBase/properties/to'
date-received:
$ref: '#/components/schemas/messageBase/properties/date-received'
error-code:
$ref: '#/components/schemas/error-code'
error-code-label:
$ref: '#/components/schemas/error-code-label'
xml:
name: rejection
required:
- account-id
- from
- to
- date-received
- error-code
- error-code-label
error-code:
type: string
description: Will be set if the `status` is not `accepted`.
example: '0'
enum:
- '0'
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
- '7'
- '8'
- '9'
- '10'
- '11'
- '12'
- '13'
- '14'
- '15'
- '99'
- '400'
- '401'
x-ms-enum:
name: error-code
values:
- value: '0'
description: Delivered.
- value: '1'
description: >-
Unknown - either; An unknown error was received from the carrier
who tried to send this this message. _or_ Depending on the
carrier, that `to` is unknown. When you see this error, and
`status` is rejected, always check if `to` in your request was
valid.
- value: '2'
description: >-
Absent Subscriber Temporary - this message was not delivered
because `to` was temporarily unavailable. For example, the handset
used for `to` was out of coverage or switched off. This is a
temporary failure, retry later for a positive result.
- value: '3'
description: >-
Absent Subscriber Permanent - `to` is no longer active, you should
remove this phone number from your database.
- value: '4'
description: >-
Call barred by user - you should remove this phone number from
your database. If the user wants to receive messages from you,
they need to contact their carrier directly.
- value: '5'
description: >-
Portability Error - there is an issue after the user has changed
carrier for `to` If the user wants to receive messages from you,
they need to contact their carrier directly.
- value: '6'
description: >-
Anti-Spam Rejection - carriers often apply restrictions that block
messages following different criteria. For example, on SenderID or
message content.
- value: '7'
description: >-
Handset Busy - the handset associated with `to` was not available
when this message was sent. If `status` is `Failed` this is a
temporary failure; retry later for a positive result. If `status`
is `Accepted` this message has is in the retry scheme and will be
resent until it expires in 24-48 hours.
- value: '8'
description: >-
Network Error - a network failure while sending your message. This
is a temporary failure, retry later for a positive result.
- value: '9'
description: >-
Illegal Number - you tried to send a message to a blacklisted
phone number. That is, the user has already sent a STOP opt-out
message and no longer wishes to receive messages from you.
- value: '10'
description: >-
Invalid Message - the message could not be sent because one of the
parameters in the message was incorrect. For example, incorrect
`type` or `udh`
- value: '11'
description: >-
Unroutable - the chosen route to send your message is not
available. This is because the phone number is either; Currently
on an unsupported _or_ network. On a pre-paid or reseller account
that could not receive a message sent by `from` To resolve this
issue either email us at
[support@nexmo.com](mailto:support@nexmo.com) or create a helpdesk
ticket at [https://help.nexmo.com](https://help.nexmo.com).
- value: '12'
description: >-
Destination unreachable - the message could not be delivered to
the phone number.
- value: '13'
description: >-
Subscriber Age Restriction - the carrier blocked this message
because the content is not suitable for `to` based on age
restrictions.
- value: '14'
description: >-
Number Blocked by Carrier - the carrier blocked this message. This
could be due to several reasons. For example, `to` s plan does not
include SMS or the account is suspended.
- value: '15'
description: >-
Pre-Paid - Insufficent funds - `to`’s pre-paid account does not
have enough credit to receive the message.
- value: '99'
description: >-
General Error - there is a problem with the chosen route to send
your message. To resolve this issue either email us at
[support@nexmo.com](mailto:support@nexmo.com) or create a helpdesk
ticket at [https://help.nexmo.com](https://help.nexmo.com).
- value: '400'
description: wrong parameters
- value: '401'
description: authentication failed
error-code-label:
type: string
description: A text label to explain `error-code`.
example: Delivered
error:
type: object
properties:
error-code:
$ref: '#/components/schemas/error-code'
error-code-label:
$ref: '#/components/schemas/error-code-label'
errorJson:
type: object
properties:
type:
type: string
example: BAD_REQUEST
error_title:
type: string
example: Bad Request
invalid_parameters:
type: object
additionalProperties:
type: string
example: Is required.
errorXml:
type: object
xml:
name: error
properties:
type:
type: string
example: BAD_REQUEST
error_title:
type: string
example: Bad Request
invalid_parameters:
type: array
items:
type: object
xml:
name: entry
properties:
key:
type: string
example: date
value:
type: string
example: Is required.
securitySchemes:
apiKey:
type: apiKey
name: api_key
in: query
description: >-
You can find your API key in your [account
overview](https://dashboard.nexmo.com/account-overview)
apiSecret:
type: apiKey
name: api_secret
in: query
description: >-
You can find your API secret in your [account
overview](https://dashboard.nexmo.com/account-overview)
You can’t perform that action at this time.