API requests and responses

Use these formatting rules, headers, and patterns when you send requests to the Infobip API and parse its responses.

Conventions

The following formatting rules apply across the API:

• Phone numbers: Provide phone numbers in international E.164(opens in new tab) format: country code followed by the subscriber number, digits only, without a leading + or 00. For example, +41 79 302 67 27 is sent as 41793026727.

• Dates and times: Date-time values in requests and responses use ISO 8601 format with a time-zone offset, for example 2017-07-20T06:47:45.777+0000. The format pattern is yyyy-MM-dd'T'HH:mm:ss.SSSZ. The offset has no colon (+0000, not +00:00), so some parsers need this pattern set explicitly.

  Different offsets can represent the same instant. For example, 2017-07-20T06:47:45.777+0000 and 2017-07-20T07:47:45.777+0100 are equal. The offset reflects the time zone configured for your account, user, or API key, so treat it as variable.

  Parse values into the native date-time type of your language and let it handle the offset. For code samples, see Date formats in Backward compatibility.

• Prices and currency: Prices in responses use the charging currency of your account. To change the charging currency, contact your account manager or Support.

• URL encoding: Query parameters in the API reference examples are not URL encoded, so they stay readable. If your HTTP library does not encode query parameters automatically, encode them yourself. For example, the + in sentSince=2026-01-01T00:00:00.000+0100 is read as a space unless you send it as %2B. With curl, use -G with --data-urlencode, as in the Pagination example.

Content types

The Content-Type header tells the API the format of the request body, and the Accept header sets the format of the response. Most endpoints use JSON.

Request content type [#request-content-type-content-types]

Most endpoints accept application/json. Some use multipart/form-data for file uploads, and some support application/xml. Check the documentation for your target endpoint to confirm which content types it supports. Request and response bodies are UTF-8.

Any request with a body, typically POST and PUT requests, must include a Content-Type header that matches the format of the data you are sending. For example, you can format an SMS message in either JSON or XML, but you must set the Content-Type header accordingly.

The following example sends JSON. Replace {baseUrl} and {apiKey} with your own values. See API authentication.

The following example sends an email as multipart/form-data. With -F, curl sets the Content-Type header automatically. The response is JSON:

Response content type [#response-content-type-content-types]

By default, JSON and XML request bodies receive a response in the same format. Other requests, such as multipart/form-data requests and requests without a body, receive JSON. To receive the response in a different format, use the Accept header or a path extension.

Set the Accept(opens in new tab) header to the format you want the response in. The following example requests delivery reports in XML:

If you cannot set the Accept header, append .json or .xml to the request path instead (legacy). The following request returns the same XML response as the Accept header example:

Response parsing

Parse responses according to the JSON(opens in new tab) or XML(opens in new tab) specification, using the native support in your language or an established library. When you parse a response:

• Ignore fields you do not recognize. Infobip can add response fields at any time.
• Read properties by name, never by position. JSON does not guarantee the order of properties in an object.

For code samples, see Backward compatibility.

Pagination

List and log endpoints return a limited number of results per call. Set the page size with the limit query parameter, up to the maximum for the endpoint. If you omit limit, you get 50 results. For SMS logs and delivery reports, the maximum is 1000, and only the last 48 hours are available. Some endpoints also support cursor-based pagination. Check the endpoint documentation to see whether it supports cursors.

If an endpoint does not support cursors and a call returns as many results as limit, there may be more results. To retrieve them, narrow the time range and query again, for example with the sentSince and sentUntil query parameters.

For example, GET /sms/3/logs uses cursor-based pagination when you set useCursor=true. Omit cursor on the first call. The response includes a cursor object (results trimmed):

To get the next page, send useCursor=true again and set cursor to the nextCursor value. --data-urlencode encodes the value, so you can pass it as returned:

Stop when a response has no nextCursor. A page with fewer results than limit is not proof of the last page.

400 Bad Request errors

If the request body cannot be processed, the API returns HTTP 400 Bad Request. For the error response body and how to handle it, see Handling errors. The following are common causes:

• The Content-Type header is missing.
• Content-Type does not match the submitted body.
• The body is not valid JSON or XML.
• The body does not match the request model of the endpoint.