API

Intro

On this page we help you setup Neptune into your codebase just using our APIs. You might prefer to use any SDKs of your choice if that seems easier.

The Teurons Neptune API is organized around REST. Our API has predictable resource-oriented URLs, accepts json request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

To call Neptune's API, you need an API Token. You can obtain API Token from the Dashboard under Team.

Usually, though SaaS platforms provide one single API endpoint, Neptune has two:

https://api.teurons.com/neptune

Authorization

The Neptune API uses API key to authenticate requests. You can view and manage your API keys in the Neptune -> Team Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via Bearer Auth. Provide your API key as the value to Authorization Header.

Authorization: Bearer <api token>

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Note: Especially for Ingest an Event API, please check it's relevant documentation

---

Events

You would be ingesting events to Neptune Platform whichever you think should be used to analyze and send user communication.

Ingest An Event

You can find the entire event data structure here, we will cover the most basic schema of the structure.

Instead of using api.teurons.com, but ingesting events, you can use our Edge APIs which are globally available and give you response in < 100 ms.

Endpoint

POST https://edge.teurons.com/neptune/events/ingest

Note: For this endpoint, you would be sending API Token as part of payload and not Authorization header.

Example Basic Event:

{
    "environment": "dev",
    "api_token": "{{api_token}}",
    "event_type": "request_otp_to_verify_email_during_registration",
}

The above is an example for the most basic event. To create an event, Neptune need to know three basic things:

1. environment - Mention the identifier of the environment
2. api_token - Use the JWT Token generated from Dashboard
3. event_type - Event Type though is a string, we suggest using lowercase, underscored separated string which is enough descriptive.

Users

You can learn more about Users feature here: Learn More About Users

User Object

attribute	description
user_id	You can use any string. It might be integer or uuid.
meta	Meta is a json object which you can use to store any information to identify user

You can use this API to create/update users, their profiles and their contact information, if you haven't been using this API, you can write a cron job to sync your users to Neptune. Syncing users really helps to links events to users, by passing user_id in event object.

Create User

POST https://api.teurons.com/neptune/<environment>/users

Request Payload:

{
    "user_id": "2",
    "meta": {
        "name": "Rajiv Seelam"
    }
}

Update User

PUT https://api.teurons.com/neptune/<environment>/users/<user_id>

Request Payload:

{
    "meta": {
        "name": "Rajiv Betalectic"
    }
}

Contact Info Object

A user can have many contact infos, the following object structure can help you to identify various type of information.

Note: It's important to keep in mind that Neptune uses <type,value> combination to identify an unique/distinct contact information. As in, under a user, you can't have same <type,value> combination.

attribute	description
type *	One of "email", "mobile_number", "firebase_token"
value *	Value for the above type
filterable	Optional string which you can pass to identify user contact info. Ex: You have both android and ios apps, and both use firebase for push notifications. In thise case, both are "firebase_token", to differentiate, you can use filterable. The value of filterable can be "android" and "ios" to satisfy both cases
meta	Meta is a json object which you can use to store any information to identify user

* = required

Add User Contact Info

POST https://api.teurons.com/neptune/<environment>/users/<user_id>/contacts_info

{
    "type": "email",
    "value": "rajivs.iitkgp@gmail.com",
    "filterable": "alternative",
    "meta": {
        "verified": "true"
    }
}

Update User Contact Info

PUT https://api.teurons.com/neptune/<environment>/users/<user_id>/contacts_info

{
    "type": "mobile_number",
    "value": "+91989",
    "filterable": "regular",
    "meta": {
        "android": "true"
    }
}

Delete User Contact Info

DELETE https://api.teurons.com/neptune/<environment>/users/<user_id>/contacts_info

{
    "type": "mobile_number",
    "value": "+91"
}

App Notifications

Read Notifications for an User

GET https://api.teurons.com/neptune/app_notifications/<environment>?per_page=10&page=1&user_id=<user_id>&type=all

Possible values for type: all, unread, read

Default is "unread"

Mark an App Notification as Read

POST https://api.teurons.com/neptune/app_notifications/<environment>/read

You can mark notification as read in two ways:

Mark all notifications of an user as read

{
    "type": "user",
    "id": "<user_id>"
}

Mark a particular notification as read

{
    "type": "notification",
    "id": "<notification_uuid>"
}