Using API

In this article you'll find out about Backend API endpoints, how calls are made, status codes, filters, sorting, pagination, http methods.

API types

We have one API:

Backend API (server side)

Backend API is a secure way to exchange information between our system and your store or website.

Endpoints

Backend API endpoint: https://api.omnisend.com/v3/

<script type="text/javascript">

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

</script>

Replace <YOUR_BRAND_ID> with your brandID, 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

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&after=NWIwZmY1NDQxMDcwZDdkY2RlNjYwYWMw&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

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/carts?sort=createdAt

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

Pagination

In Backend API to limit response results limit parameter is used:

limit – default 100, max - 250.

To get paged results, pass these parameters in query.

Example:
GET https://api.omnisend.com/v3/campaigns?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)
limit - currently used limit

Use next and previous links to get next or previous page of results.

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.