Sirena API (1.10.0)

Download OpenAPI specification:Download

Overview

Welcome to our API reference!

This is the reference documentation for the Sirena REST API. This API is based on resources which are represented by JSON format and are manipulated using the HTTP protocol.

What can this API do?

  • Send Lead data for agents to work with.
  • Access and manage the database of contacts stored in Sirena.
  • Subscribe and be notified via webhooks when some events occur in Sirena, i.e:
    • An interaction with a contact occurs. An interaction can be anything from a message to a reminder to an agent note.
    • A new contact is created.

And much more...

Prerequisites

Before using this API you will need:

  1. A Sirena account. You need to have an access to a Sirena account in order to use the API.
  2. An API Key. You can create a one-off API Key by installing the "API access" App from the App Marketplace.
    • Full-fledged Apps are granted one API Key per instance. See App Lifecycle for more information.

Glossary

These are some of the terms we use across the API.

Lead

In Sirena, a lead is a piece of information that allows an agent to contact a potential client. To be useful, this information should include:

  • Contact information
  • Product or service the potential client is interested in, according to the industry your business is related to.

Prospect

A contact or prospect can be added to Sirena in two ways:

  • From a lead, generally acquired through a marketing channel.
  • Manually by an agent using the Sirena app.
  • It is important to understand that not every lead will generate a new prospect. Sirena can detect duplicate leads and merge them into a single prospect.

Authentication

api_key

Requests made to the API you must include a valid API Key as a query string parameter. For example:

GET https://api.getsirena.com/v1/prospect/56b367bffdc27b03003fc3ee?api-key=YOUR_api_key
Security Scheme Type API Key
Query parameter name: api-key

API Scopes

API Keys enable access to the API with one or more Scopes. Each API Scope enables set of API features.

Scope Permissions
leads:write Send lead data for agents to work with.
prospects:read Read prospects, operations and quotes.
prospects:readAdditionalData Read prospects and quote additional data.
prospects:write Create new quotes, update quotes, delete prospects, etc.
notifications Subscribe to notifications via webhooks.
messages:channels List available conversational channels for prospects.
messages:transactional Send transactional messages like appointment information, delivery and shipping notifications.
messages:conversational Send conversational messages for automatic replies, chatbots, and other use cases.
integration:act-as-user Perform operations as a user.

Rate Limits

API Rate Limits are in place to protect Sirena from API traffic spikes that could put our databases at risk. We therefore measure the amount of requests sent to the API in order to throttle these when they surpass the amount allowed. We will respond with 429 Too Many Requests and the following headers:

  • By default, we have set 200 RPM (Requests per minute) per API Key
Header Name Header Description
X-RateLimit-Limit Maximum number of requests allowed for the app.
X-RateLimit-Remaining Number of requests left in the current time.
X-RateLimit-Reset Time when the number of requests will be reset to the maximum limit.

When does the amount of requests reset?

The amount of permitted requests resets every 60 seconds

Leads

The following endpoints allow creating and registering Leads. Leads include information about the product or service of interest, which means different lead schemas depending on the industry.

Send Retail Lead

Processes lead data and returns the matching prospect. If the prospect already exists, previous lead data will not be returned. Retail industry only.

Authorizations:
Request Body schema: application/json
priority
number

The priority of the Lead

provider
string

The name/key to identify the provider of the lead.

providerLeadId
string

The ID of the lead in the provider.

utmSource
required
string

Identify the advertiser, site, publication, etc. that is sending traffic to your property.

utmMedium
string

The advertising or marketing medium.

utmCampaign
string

The individual campaign name, slogan, promo code, etc. for a product.

firstName
string
lastName
string
phones
Array of strings
emails
Array of strings <email>
object

@deprecated use NewCallEvent An object representing an inbound phone call. Connected calls should provide a recording and its associated metadata.

category
string

The category of the lead. Use the Categories endpoint to see the available categories. If skipped, the default category is used.

Array of objects (Nin)

National Identification Number

address
string

Full street address.

subLocality
string

County / other sub-division of a locality, such as communes departments, etc.

locality
string

City / Municipality.

region
string

State / Province.

country
string
zipCode
string

Zip Code / Postal Code.

listingTitle
string

The title of the listing page.

listingUrl
string

The URL of the listing page.

comments
string

Any comments worth making to the agent, from the lead or from the acquisition channel.

company
string

If the lead has an assigned company, indicate it's name or code. Usually, it's the name of the company under the general account.

store
string

If the lead has an assigned store, indicate it's name or code. Usually is the name of the branch inside the company.

agent
string

If the lead has an assigned agent, indicate it's name or code.

leadId
string

@deprecated - use providerLeadId The ID of the lead in the provider.

source
string

@deprecated - use utmSource Identify the advertiser, site, publication, etc. that is sending traffic to your property.

medium
string

@deprecated - use utmMedium The contact medium where the lead came from.

campaign
string

@deprecated - use utmCampaign The individual campaign name, slogan, promo code, etc. for a product.