Using API


In this article you'll find out about API types (Backend and Frontend/Javascript), endpoints, how calls are made, status codes, filters, sorting, pagination, http methods.


API types

We have two types of API:
  • Backend API (server side)
  • Frontend/Javascript API
Backend API is a secure way to exchange information between our system and your store or website. It has all available functionality except popups and forms (you need to use Javascript snippet - part of Frontend API - for them to work).

Frontend API (including Javascript snippet) is front-end based API with limited functionality - it is used to POST contacts, orders, carts, add or remove contacts from lists, mark discount codes as used. Also it is used for forms, popups and Product Picker.

You can use only Backend API, Frontend API or combine both. It's up to you which API to choose.


Endpoints

Backend API endpoint: https://api.omnisend.com/v3/
Frontend API - to use Frontend API you need to add Javascript code to the HEAD of all your pages (this step is done while registering at Omnisend):

<script type=" text/javascript">
window.omnisend = window.omnisend || [];
omnisend.push([ "accountID", " <YOUR_ACCOUNT_ID>"]);
! function(){ var e=document. createElement( "script");e.type= "text/javascript",e. async=!0,e.src= "https://omnisrc.com/inshop/launcher.js"; var t=document. getElementsByTagName( "script")[0];t.parentNode. insertBefore(e,t)}();
</script>

Replace <YOUR_ACCOUNT_ID> with your accountID, which you can find in app.omnisend.com panel, by clicking on account name at the top of the screen, selecting My Account and navigating to Integrations & API part.

If you already have connected your store or application with Omnisend - you have already added this snippet.

Responses

Backend API
With every API request you'll receive HTTP status code and if error occurs - error variable with error description.
All error codes, starting with 4 (for example 400) indicates an error from your end, 503 status code indicates server error.
Status codes starting with 2 (for example 200) indicates successful requeest.

You can find all status codes with description in API Reference

Frontend API - while adding Javascript code blocks you can define your own callback success and error functions.
In every code snippet you'll see code:
<script type=" text/javascript">
...
callbacks: {
onSuccess: function() {
console. log( "ok");
},
onError: function() {
console. log( "error!");
}
</script>

Write your own success and error functions, or just leave default - they will output to developer console only if request was successful or there was an error.


Filters

In Backend API filters are available by passing query strings.
If available, filters for every method are described in method description.
They are used as query strings, for example, if we want to get contacts with type - active and country - USA, we use:

https://api.omnisend.com/v3/contacts?status=subscribed&country=US&offset=10&limit=10

Note: you need to encode query strings (encode only separate parameters and not all request URL).
For example if you want to use email as filter, you need to encode it.

Example:
https://api.omnisend.com/v3/contacts/?email=test%40omnisend.com

If you use PHP you can encode parameters using urlencode function: http://php.net/manual/en/function.urlencode.php

Filters are not used in Frontend API, while there no GET methods exists.


Sorting

In Backend API it is possible to sort GET method results by adding query parameter sort.
Sort order and available sorting options are described in every method.
Example:
GET https://api.omnisend.com/v3/contacts?status=subscribed&sort=sent

Note: API calls with sort parameter are slower, so you can expect longer response time (it depends on database size).

Sorting is not used in Frontend API, while there no GET methods exists.

Pagination

In Backend API to limit response results offset and limit parameters are used:
  • offset – default 0.
  • limit – default 100, max - 250.
To get paged results, pass these parameters in query.

Example:
GET https://api.omnisend.com/v3/campaigns?offset=0&limit=20

Important: please check response status code and if not 2xx code is returned - stop fetching results.

In paged response you'll get paging object with parameters:
  • previous - link to get previous results (if available)
  • next - link to get next results (if available)
  • offset - currently used offset
  • limit - currently used limit


Pagination is not used in Frontend API, while there no GET methods exists.


HTTP methods

Backend API supports 5 HTTP methods for interacting with resources:
  • GET – request used to retrieve data. Never used to delete, update or insert data.
  • POST – request used to insert data. Posted data type – JSON.
  • PATCH – request used to update data. Only passed data will be updated. You don’t need to provide all data set.
  • PUT – create or update (replace) a resource. Useful for syncing data.
  • DELETE – remove data.
  • PATCH and PUT difference

POST, PUT and PATCH difference
HTTP POST requests used to create new resource.
HTTP PATCH requests used to make partial update on a resource.
PUT requests are used to modify/replace all resource entity.

PATCH method is the correct choice for partially updating an existing resource and PUT should only be used if you’re replacing a resource entirely.

HTTP Method tunneling

HTTP Method tunneling can be used by making POST operation and providing needed method in an X-HTTP-Method-Override header.

So if you can't use PATCH, PUT or DELETE methods - you can use POST and X-HTTP-Method-Override header to set PUT, PATH or DELETE operation.