Look Up a Set of Messages

Use this endpoint to retrieve a list of Message Detail Records (MDRs) within a specified date range. Date and time is based on Coordinated Universal Time (UTC).

Endpoint

GET /messages

Request Parameters

All parameters are optional except where noted.

• start_date

  datetime required

  The beginning date and time, in UTC, on which to perform an MDR search. The DateTime can be formatted as YYYY-MM-DDor YYYY-MM-DDTHH:mm:ss.SSZ.

• end_date

  datetime

  The ending date and time, in UTC, on which to perform an MDR search. The DateTime can be formatted as YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.SSZ.

• limit

  integer

  The number of MDRs to retrieve at one time. You can set as high of a number as you want, but the number cannot be negative and must be greater than 0 (zero).

• offset

  integer

  The number of MDRs to skip when performing a query. The number must be 0 (zero) or greater, but cannot be negative.

Response Fields

The following is an explanation of the different response objects and fields.

• data

  Object composed of attributes, type ,id.

• attributes

  The Attributes object contain the following

  • body - The message content.

  • direction - The direction of the message. For a sent message, this is outbound. For a received message this is inbound.

  • amount_nanodollars - The cost of the message in nanodollars. The displayed nanodollars amount is the USD amount_display value multiplied by 1,000,000,000 (one billion) for a corresponding whole number.

  • message_encoding - Indicates the encoding type, which will be either 0 (UTF-8) or 8(UCS-2). See Message Length & Concatenation for more information.

  • timestamp - Date and time, to the second, on which the message was sent. This field displays UTC time using an ISO 8601 format.

  • to - The phone number to which the message was sent.

  • is_mms - Boolean value indicating whether or not the message includes a multimedia file. True indicates yes, while False indicates no. Currently, MMS is not supported; therefore, this field will always be false.

  • amount_display - The total cost of the message in USD. If a message was broken into multiple pieces due to concatenation, this amount will be the total amount for all message pieces. This field does not display out to eight decimal points. See "Message cost" in Message Length & Concatenation for more information.

  • from - The Flowroute phone number from which the message was sent.

  • callback_url - The callback URL defined for the Flowroute number on the Preferences > API Control page; otherwise, the value is null.

  • message_typeIndicates the type of message, either long-code or toll-free. If the message was sent to or received from another phone number, this field displays long-code. If it was sent to or received from a toll-free number, this field displays toll-free.

• type

  Defines what the object is. Because SMS is the only supported object type, this field will always display message.

• id

  The unique record identifier of a sent message.

Formatting

DateTime Format

The start_date and end_date parameters accept UTC DateTime strings formatted in accordance with ISO 8601. These parameters can be as general as YYYY-MM-DD—for example, 2016-12-30; or, as specific as YYYY-MM-DDTHH:mm:ss.SSZ—for example, 2016-12-30T14:34:01.321Z.

HTML URL Encoding

ISO 8601 utilizes two characters that must be HTML URL encoded. These characters, and their related URL-encoded formats, are:

• : (colon), encoded as %3A
• + (plus), encoded as %2B