NAV
shell

Introduction

Welcome to Jellyreach API documenation!

In this documentation, you can find everything you need to start sending your data to Jellyreach.

In case you need any help, feel free to reach us at [email protected].

Authentication

curl --request GET \
  --url https://api.jellyreach.com/v1/contacts \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

To authenticate against Jellyreach API, you need to use your API key in each request.

To access your API key you need to visit API keys within your account.

All requests must be made over HTTPS and header must contains the following parameters:

Header Value
Accept application/json
Authorization YOUR_API_KEY

Errors

Jellyreach uses conventional HTTP response codes to indicate success or failure of an API request.

Codes in the 2xx range mean success, codes in the 4xx mean there was an error in the data passed to Jellyreach' API (such as missing parameters) and codes in the 5xx range indicate an error with Jellyreach internal servers.

Error Codes

Code Description
200 - OK The request was successful
400 - Bad Request Bad request
401 - Unauthorized Your credentials are invalid
404 - Not Found The resource doesn’t exist
50X - Internal Server Error An error occurred with our API

Contacts

Get Contacts

curl --request GET \
  --url https://api.jellyreach.com/v1/contacts \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{
  "current_page": 1,
  "data": [
    {
      "attributes": {
        "contact_id": "600fee7ad50ade7cd25303a2",
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "city": "London"
      },
      "channels": {
        "email": {
          "subscribed": false
        },
        "sms": {
          "subscribed": true
        },
        "viber": {
          "subscribed": false
        }
      },
      "created_at": "2021-01-26 10:27:06",
      "updated_at": "2021-01-26 10:27:22"
    }
  ],
  "first_page_url": "http:\/\/api.jellyreach.com\/api\/v1\/contacts?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "http:\/\/api.jellyreach.com\/api\/v1\/contacts?page=1",
  "next_page_url": null,
  "path": "http:\/\/api.jellyreach.com\/api\/v1\/contacts",
  "per_page": 25,
  "prev_page_url": null,
  "to": 3,
  "total": 3,
  "exact": true
}

Get all contacts.

HTTP Request

GET https://api.jellyreach.com/v1/contacts

Create Contact

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d 'contact_id=john-doe-123' \
  -d '[email protected]' \
  -d 'first_name=John' \
  -d 'last_name=Doe' \
  -d 'gender=Male' \
  -d 'city=London' \
  -d 'country=UK' \
  -d 'birthday=1990-01-01'

The above command returns JSON structured like this:

{"message": "Contact has been successfully created."}

Create a new contact.

HTTP Request

POST https://api.jellyreach.com/v1/contacts

Parameters

Attribute Required Input Type Description
contact_id Yes String Contact ID in your internal system.
email No String Unique email
first_name No String First name
last_name No String Last name
phone No String Phone
gender No String Gender
birthday No Date (YYYY-MM-DD) Birthday
city No String City
country No String Country

Some of your attributes might be required if you have changed it in the attributes settings.

If you have created custom attributes, you need to send them as well (if required).

Update Contact

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'
  -d 'city=New York City'

The above command returns JSON structured like this:

{"message": "Contact has been successfully updated."}

Update an existing contact.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}

Parameters

Attribute Input Type Description
city String Contact's new city.

Send only attributes you wish to update. In this example, we're updating only city attribute.

However, we can send more attributes if we wished.

Subscribe Contact

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/{contact_id}/subscribe \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{"message": "Contact has been successfully subscribed to sms."}

Unsubscribe an existing contact.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}/subscribe

Parameters

Attribute Required Input Type Description
channel Yes String Channel you want to subscribe a contact for.

Unsubscribe Contact

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/{contact_id}/unsubscribe \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{"message": "Contact has been successfully unsubscribed to sms."}

Unsubscribe an existing contact.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}/unsubscribe

Parameters

Attribute Required Input Type Description
channel Yes String Channel you want to unsubscribe a contact for.

Create Event

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/{contact_id}/events \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d 'event=add_to_cart'
  -d 'event_data={"product": "T-Shirt", "price": 100}'
  -d 'created_at=2021-01-01 10:20:30'

The above command returns JSON structured like this:

{"message": "Event has been queued. It will be processed as soon as possible."}

Create event to an existing contact.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}/events

Parameters

Attribute Required Input Type Description
event Yes String Event key.
event_data Yes JSON Event data.
created_at Yes Datetime Date and time.

You can add custom events if you need to track additional data.

Add to List

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/{contact_id}/events \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d 'event=add_to_cart'

The above command returns JSON structured like this:

{"message": "Contact has been successfully added to the list."}

Add existing contact to a list.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}/lists

Parameters

Attribute Required Input Type Description
contact_list_id Yes JSON Contact list's ID.

Delete from List

curl --request DELETE \
  --url https://api.jellyreach.com/v1/contacts/{contact_id}/lists/{contact_list_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{"message": "Contact has been successfully deleted from the list."}

Delete contact from the list

HTTP Request

POST https://api.jellyreach.com/v1/contacts/{contact_id}/lists/{contact_list_id}

View Contact

curl --request GET \
  --url https://api.jellyreach.com/v1/contacts/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json'

The above command returns JSON structured like this:

{
  "id": "5ff50f11c41fb60426487be2",
  "attributes": {
    "contact_id": "1",
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "",
    "gender": "Male",
    "city": "",
    "country": "",
    "birthday": "1990-01-01"
  },
  "channels": {
    "email": {
      "subscribed": true
    },
    "sms": {
      "subscribed": true
    },
    "viber": {
      "subscribed": true
    }
  },
  "created_at": "2021-01-06 01:14:57",
  "updated_at": "2021-01-28 15:53:49"
}

Get an existing contact.

HTTP Request

DELETE https://api.jellyreach.com/v1/contacts/{contact_id}

Delete Contact

curl --request DELETE \
  --url https://api.jellyreach.com/v1/contacts/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{"message": "Contact has been successfully deleted."}

Delete an existing contact.

HTTP Request

DELETE https://api.jellyreach.com/v1/contacts/{contact_id}

Lists

Get Lists

curl --request GET \
  --url https://api.jellyreach.com/v1/contacts/lists \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "list": "Example List",
      "contacts": 1000,
      "created_at": "2022-06-06T12:34:38.000000Z",
      "updated_at": "2022-06-06T12:39:49.000000Z"
    },
    {
      "id": 2,
      "list": "Another List",
      "contacts": 2500,
      "created_at": "2022-06-06T12:34:38.000000Z",
      "updated_at": "2022-06-06T12:34:38.000000Z"
    }
  ],
  "from": 1,
  "to": 2,
  "last_page": 1,
  "total": 2,
  "has_more": false
}

Get all contact lists

HTTP Request

GET https://api.jellyreach.com/v1/contacts/lists

Create List

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/lists \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d 'list=Example List'

The above command returns JSON structured like this:

{"message": "Contact list has been successfully created."}

Create a new list.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/lists

Parameters

Attribute Required Input Type Description
list Yes String Contact list's name.

Update List

curl --request POST \
  --url https://api.jellyreach.com/v1/contacts/lists/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d 'list=Example List'

The above command returns JSON structured like this:

{"message": "Contact list has been successfully updated."}

Update a new list.

HTTP Request

POST https://api.jellyreach.com/v1/contacts/lists

Parameters

Attribute Required Input Type Description
list Yes String Contact list's name.

View List

curl --request GET \
  --url https://api.jellyreach.com/v1/contacts/lists/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{
  "data": {
    "id": 1,
    "list": "Example List",
    "contacts": 1000,
    "created_at": "2022-06-06T12:34:38.000000Z",
    "updated_at": "2022-06-06T12:39:49.000000Z"
  }
}

Get an existing list.

HTTP Request

GET https://api.jellyreach.com/v1/contacts/lists/{id}

Delete List

curl --request DELETE \
  --url https://api.jellyreach.com/v1/contacts/lists/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: YOUR_API_KEY'

The above command returns JSON structured like this:

{"message": "Contact list has been successfully deleted."}

Delete a list.

HTTP Request

DELETE https://api.jellyreach.com/v1/contacts/lists/{id}

shell