Get Started with Infobip API

This documentation contains the entire Infobip API offering. One quick glance at the left-side navigation menu reveals the Infobip product stack. Each product contains documentation for every available API endpoint and a webhook.

Trial account

While Infobip API is free to explore for everyone, you will need an Infobip account to use it. After the quick sign-up process, you will get your API key and Base URL which is all you need to start using any API. During the trial period you will have some limitations depending on the product you choose. Typically, these are:

• the number of free messages you can send per channel
• the type of recipients - usually, you'll only be able to send messages to your own number or email account registered when signing up
• sender IDs - you will only be able to use a predefined Infobip demo sender

The trial is valid for 60 days from the day of account creation. Similarly to a paying account, the performance of your API is influenced by throttling, throughput, and other carrier-related restrictions. Learn more about the trial here.

Authentication

We support multiple authentication methods. Our recommendation is to use API key header whenever possible.

Once logged in, find your API key at the top of this page, within the web interface homepage, or the API key management page.

Base URL and data centers

Each Infobip account has its unique Base URL which you should use in every API request you make. If you are logged into Infobip, you will find your Base URL at the top of this page, and it will already be injected in every API endpoint and code example throughout all documentation.

We use the base URL to route your request to the correct "regulatory region" and to optimize your traffic between data centers with the region. Base URL is also used by our Support teams for troubleshooting.

Learn more about Base URLs.

OpenAPI Specification

To ensure Infobip APIs comply with the industry standards and can be easily integrated, they are all designed according to the OpenAPI Specification framework.

See the Infobip OpenAPI Specification.

SDKs

We, at Infobip provide you with official API client libraries and SDKs in various programming languages. To see all SDKs, refer to our SDKs page in our Developer Hub.

When it comes to new releases, we follow what is known as Semantic Versioning 2.0.0 standard. In short, that means when we release patches or minor updates, you are safe to update to a new version, because backward compatibility is preserved. All major releases will always contain changes incompatible with previous versions.

All our API-related SDKs are open sourced and available on GitHub. Our libraries are built on top of the OpenAPI Specification and powered by OpenAPI Generator. This means we do not accept pull requests on those GitHub repositories. However, we strongly encourage you to open new issues in our repositories, as stated in contributing guidelines.

Code examples

For each API endpoint, we provide one or more use case examples. Each use case has including/excluding parameters on how to complete a task (e.g., Send basic text SMS, send scheduled SMS, send SMS in a specific language, etc.) Each code example is available in multiple programming languages, as well as cURL command, and as a request payload in JSON or XML. Code examples are auto generated from the Open API specification using the Postman code generator. You can copy code examples and use them in your project.

Webhooks

If you want to be notified about certain events, such as message delivered status or incoming message status, use webhooks. Webhooks are standard HTTP endpoints implemented in your application that will accept and handle HTTP requests from Infobip. Basically, webhooks save you from having to continuously send requests to the Infobip server asking for message delivery status. Instead, available delivery statuses are forwarded to a provided endpoint. These requests are usually POST requests containing payload in JSON format. Manage and configure your webhooks using the Subscription Management API.

If you want to protect your endpoints from spam, you can use our IP addresses to whitelist the traffic from the Infobip platform. Check out the safe list of IP addresses.If you want to protect your endpoints from spam, you can use our IP addresses to whitelist the traffic from the Infobip platform. Check out the safe list of IP addresses.

Status and error codes

When it comes to status codes, we provide the result status codes (which are sent back by the server for any HTTP transaction), as well as API status codes. Find the API Status codes in the response of sent message(s), delivery reports and/or message logs. They are there to help you track the status of sent messages, but can also be very useful when troubleshooting. Error codes, similar to status codes, can also be returned as part of the response for sent message(s) and delivery reports.

Usually, the status you might receive within a response is one with the ID 26, called PENDING_ACCEPTED. It notifies you that the message you wanted to send has been accepted, processed, and it's ready to be sent to the operator.

When it comes to response statuses, the point is to receive one without an error. For example, one with the ID 0 with the name NO_ERROR.

For detailed information, refer to Response Statuses and Error Codes.

Versioning and API lifecycle

The URL of each documented API endpoint contains a current API version number. The endpoint version will change only if a breaking change is introduced. Adding a new field, for example, is not considered a breaking change. However, removing a field or a model structure change is a breaking change. When you introduce a new version, the old one is labeled in documentation as "deprecated".

We will never completely retire an API endpoint without notifying you at least 6 months in advance.

There are exceptions to this rule. For example, for products and endpoints labeled as "early access". In those cases, you need to be prepared to keep up, iterate faster, and experiment with us. Even though the endpoint is flagged as early access, if we detect in our logs that you have been using the API recently, we will notify you about the change.

As always, we appreciate your feedback but in this phase, it's especially valuable to us, so please reach out to us.

Throughput and throttling

The question we often get is how much traffic can our API handle. This depends on which API endpoint is called.

Message sending APIs do not have an upper limit. Many of the largest global enterprises are sending messages over our APIs and we have enough capacity to handle their traffic peaks with resources to spare. However, be aware of bottlenecks that may occur with specific channel providers that sit between Infobip and message recipients. For more details, visit channel documentation for the product you are interested in.

Every API endpoint that is not sending messages is configured to throttle requests, if the usage goes well over its common use cases. If this happens, you will get an HTTP status code 429 (Too Many Requests). It is usually a sign that you are using the API endpoint in a way that was not designed to be used. In these situations, you may want to explore other endpoints which may be more suitable for your use case, or you could reach out for advice.

Our throttling mechanism is configured based on the maximum number of requests in a unit of time. So if you stop sending API requests and wait it out a bit, you will be able to call the API again.

Best practices

We are working extra hard to make the smoothest experience for developers using our API. One of the ways we try to make that happen is by focusing on consistency in following certain approaches, standards, and practices.

You may have noticed that code examples in our documentation are not URL encoded. If are dependent on a system, programming language, or library that requires explicit URL encoding for request query parameters, you will need to do it yourself. The major reason behind such a decision was that we simply want to keep our code examples easy to read and understand. Moreover, for the majority of programming languages and libraries which trigger HTTP calls, that will be done under the hood.

Refer to Integration Best Practices for more information about how to avoid potential issues, supported date formats, request/response body types, and other coding practices we recommend you follow while using our API.

Best practices are here to make all of our lives easier, so don’t shy away from checking them in more detail.

Integrations and partnership program

Before you start working on your integration solution, you might want to explore existing integrations to check if someone hasn't already created one and made it available for others to use.

If you believe that your solution could be interesting for a broader audience, we invite you to reach out to the Partnerships team. We love seeing how other platforms benefit from our connectivity offering.

Our Partnership Program offers many benefits such as free professional services, training and certification from our global experts, on-site sales and presales support, and marketing development funds.

Help and support

If you got stuck, here's what you can do:

• Check the uptime status of the product in use.
• Use our Documentation Hub. There's a good chance you'll find your answers there.
• If you have a more general question or you're struggling to get something to work, consider Stack Overflow or Twitter.
• If you've found a bug or have an account-specific question, create a ticket for our Support team.