Documentation Powered by ReDoc

Zenvia Conversion API (1.10.0)

Download OpenAPI specification:Download

Zenvia Conversion IT: [email protected] URL: https://www.zenvia.com/produtos/zenvia-conversion License: Apache 2.0

Overview

Welcome to our API reference!

This is the reference documentation for the Zenvia Conversion 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 Zenvia Conversion.
  • Subscribe and be notified via webhooks when some events occur in Zenvia Conversion, 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 Zenvia Conversion account. You need to have an access to a Zenvia Conversion 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 Zenvia Conversion, 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 Zenvia Conversion in two ways:

  • From a lead, generally acquired through a marketing channel.
  • Manually by an agent using the Zenvia Conversion app.
  • It is important to understand that not every lead will generate a new prospect. Zenvia Conversion 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://conversion.zenvia.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 Zenvia Conversion 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:
api_key
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 email, phone or id.

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.

Array of objects (NewEvent)

Ordered list of lead events

object (Product)

Responses

Request samples

Content type
application/json
{
  • "priority": 0,
  • "provider": "Webmotors",
  • "providerLeadId": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "utmMedium": "referral, organic, cpc, email, social, video",
  • "utmCampaign": "Christmas / New Year campaign",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phones": [
    ],
  • "emails": [],
  • "callIn": {},
  • "category": "used",
  • "nin": [
    ],
  • "address": "Jujuy 986, 1er piso, depto. \"A\"",
  • "subLocality": "La Perla",
  • "locality": "Mar del Plata",
  • "region": "Buenos Aires",
  • "country": "Argentina",
  • "zipCode": "7600",
  • "listingTitle": "MLA 641645231 Ferrari F430 F1 Spyder Cabriolet",
  • "listingUrl": "https://auto.mercadolibre.com.ar/MLA-641645231-ferrari-f430-f1-spyder-cabriolet-2006-roja-excelente-permuto-JM",
  • "comments": "I am interested in the Honda Civic. I will like to receive information about financing. I also have a Fiat Punto as trade in vehicle. Thanks!'",
  • "company": "Southern Group",
  • "store": "Freedom Branch",
  • "agent": "[email protected]",
  • "leadId": "string",
  • "source": "google, newsletter4, billboard, ford, bmw",
  • "medium": "cpc, banner, email newsletter, form.",
  • "campaign": "Christmas / New Year campaign",
  • "history": [
    ],
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

Send Insurance Lead

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

Authorizations:
api_key
Request Body schema: application/json
make
string

A product make is either the name of its manufacturer or, if the manufacturer has more than one operating unit, the commercial name (brand) of that unit.

model
string

A product model is the specific brand identified by a name or number.

detail
string

A product detail specific information for a product item.

sku
string

A stock keeping unit (SKU) is a product and service identification code for a store or product, often portrayed as a machine-readable bar code that helps track the item for inventory.

object (MoneyAmount)

An amount of money.

Responses

Request samples

Content type
application/json
{
  • "make": "Apple",
  • "model": "MQD32LL/A",
  • "detail": "13-inch MacBook Air\n1.8GHz dual-core Intel Core i5 processor\nTurbo Boost up to 2.9GHz\n8GB 1600MHz LPDDR3 memory\n128GB SSD storage1\nIntel HD Graphics 6000\n",
  • "sku": 6443034,
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

Send Automotive Lead

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

Authorizations:
api_key
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 email, phone or id.

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.

Array of objects (NewEvent)

Ordered list of lead events

object (VehicleProduct)

Responses

Request samples

Content type
application/json
{
  • "priority": 0,
  • "provider": "Webmotors",
  • "providerLeadId": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "utmMedium": "referral, organic, cpc, email, social, video",
  • "utmCampaign": "Christmas / New Year campaign",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phones": [
    ],
  • "emails": [],
  • "callIn": {},
  • "category": "used",
  • "nin": [
    ],
  • "address": "Jujuy 986, 1er piso, depto. \"A\"",
  • "subLocality": "La Perla",
  • "locality": "Mar del Plata",
  • "region": "Buenos Aires",
  • "country": "Argentina",
  • "zipCode": "7600",
  • "listingTitle": "MLA 641645231 Ferrari F430 F1 Spyder Cabriolet",
  • "listingUrl": "https://auto.mercadolibre.com.ar/MLA-641645231-ferrari-f430-f1-spyder-cabriolet-2006-roja-excelente-permuto-JM",
  • "comments": "I am interested in the Honda Civic. I will like to receive information about financing. I also have a Fiat Punto as trade in vehicle. Thanks!'",
  • "company": "Southern Group",
  • "store": "Freedom Branch",
  • "agent": "[email protected]",
  • "leadId": "string",
  • "source": "google, newsletter4, billboard, ford, bmw",
  • "medium": "cpc, banner, email newsletter, form.",
  • "campaign": "Christmas / New Year campaign",
  • "history": [
    ],
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

Send Saving Plan Lead

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

Authorizations:
api_key
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 email, phone or id.

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.

Array of objects (NewEvent)

Ordered list of lead events

object (SavingPlanProduct)

Responses

Request samples

Content type
application/json
{
  • "priority": 0,
  • "provider": "Webmotors",
  • "providerLeadId": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "utmMedium": "referral, organic, cpc, email, social, video",
  • "utmCampaign": "Christmas / New Year campaign",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phones": [
    ],
  • "emails": [],
  • "callIn": {},
  • "category": "used",
  • "nin": [
    ],
  • "address": "Jujuy 986, 1er piso, depto. \"A\"",
  • "subLocality": "La Perla",
  • "locality": "Mar del Plata",
  • "region": "Buenos Aires",
  • "country": "Argentina",
  • "zipCode": "7600",
  • "listingTitle": "MLA 641645231 Ferrari F430 F1 Spyder Cabriolet",
  • "listingUrl": "https://auto.mercadolibre.com.ar/MLA-641645231-ferrari-f430-f1-spyder-cabriolet-2006-roja-excelente-permuto-JM",
  • "comments": "I am interested in the Honda Civic. I will like to receive information about financing. I also have a Fiat Punto as trade in vehicle. Thanks!'",
  • "company": "Southern Group",
  • "store": "Freedom Branch",
  • "agent": "[email protected]",
  • "leadId": "string",
  • "source": "google, newsletter4, billboard, ford, bmw",
  • "medium": "cpc, banner, email newsletter, form.",
  • "campaign": "Christmas / New Year campaign",
  • "history": [
    ],
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

Send Real Estate Lead

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

Authorizations:
api_key
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 email, phone or id.

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.

Array of objects (NewEvent)

Ordered list of lead events

object (RealEstateProduct)

Responses

Request samples

Content type
application/json
{
  • "priority": 0,
  • "provider": "Webmotors",
  • "providerLeadId": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "utmMedium": "referral, organic, cpc, email, social, video",
  • "utmCampaign": "Christmas / New Year campaign",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phones": [
    ],
  • "emails": [],
  • "callIn": {},
  • "category": "used",
  • "nin": [
    ],
  • "address": "Jujuy 986, 1er piso, depto. \"A\"",
  • "subLocality": "La Perla",
  • "locality": "Mar del Plata",
  • "region": "Buenos Aires",
  • "country": "Argentina",
  • "zipCode": "7600",
  • "listingTitle": "MLA 641645231 Ferrari F430 F1 Spyder Cabriolet",
  • "listingUrl": "https://auto.mercadolibre.com.ar/MLA-641645231-ferrari-f430-f1-spyder-cabriolet-2006-roja-excelente-permuto-JM",
  • "comments": "I am interested in the Honda Civic. I will like to receive information about financing. I also have a Fiat Punto as trade in vehicle. Thanks!'",
  • "company": "Southern Group",
  • "store": "Freedom Branch",
  • "agent": "[email protected]",
  • "leadId": "string",
  • "source": "google, newsletter4, billboard, ford, bmw",
  • "medium": "cpc, banner, email newsletter, form.",
  • "campaign": "Christmas / New Year campaign",
  • "history": [
    ],
  • "product": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z",
  • "interactions": [
    ]
}

getCategories

Returns information about the lead categories available for lead creation. Note that groups can define custom rules as to when a category is valid for a given lead or not.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • "string"
]

getDefaults

Returns information about the applicable defaults for lead creation. These defaults are only used if no value is specified when creating a lead. The response includes the default currency and distance unit.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "currency": "usd",
  • "distance": "km"
}

Prospects

Querying and Deleting Prospects (customers) and their interactions with agents.

getProspects

Returns a filterable list of prospects.

If a limit is not specified, the query will return prospects from the last 31 days

If a limit is not specified, but a date or range of dates are provided, the query will return prospects within the
date or dates specified. A range of dates is considered valid if the range between them is 31 days or less

Invalid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-10-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID

Valid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID

If only one of the dates is provided, the comparison will be made with the present date
Example:

  Assuming that the present date is 2020-10-28T03:00:00.000Z

  ?createdAfter=2020-08-01:T03:00:00.000Z -> INVALID
  ?createdAfter=2020-09-30:T03:00:00.000Z -> VALID
Authorizations:
api_key
query Parameters
before
string^[a-z0-9]{24}$

Limits the results only to the prospects created before the one provided in this parameter (not included)

after
string^[a-z0-9]{24}$

Limits the results only to the prospects created after the one provided in this parameter (not included)

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

search
string

A search string to filter prospects. It can be a phone number, an email address or a name.

phoneNumber
string

A phone number string to filter prospects

category
string

The category to filter prospects.

status
string

The status to filter prospects.

agent
string^[a-z0-9]{24}$

The id of an agent to filter prospects

createdAfter
string <date-time>

The start date to filter prospects by their creation date

start
string <date-time>

@deprecated - use createdAfter The start date to filter prospects by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter prospects by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter prospects by their creation date (alias of createdBefore).

claimedAfter
string <date-time>

The start date to filter prospects by their claim date.

claimStart
string <date-time>

The start date to filter prospects by their claim date (alias of claimAfter).

claimedBefore
string <date-time>

The end date to filter prospects by their claim date.

claimEnd
string <date-time>

The end date to filter prospects by their claim date (alias of claimBefore).

transferredAfter
string <date-time>

The start date to filter prospects by their transfer date

transferStart
string <date-time>

The start date to filter prospects by their transfer date (alias of transferredAfter)

transferredBefore
string <date-time>

The end date to filter prospects by their transfer date

transferEnd
string <date-time>

The end date to filter prospects by their transfer date (alias of transferredBefore)

withAgent
boolean

A boolean specifying whether a prospect has an assigned Agent or not

group
string^[a-z0-9]{24}$

The id of a group to filter prospects

additionalData
Array of strings

List of filters for additionalData on format [FIELD][OPERATOR][VALUE].

  • FIELD: Can be any additional data field
  • OPERATOR: Can be =, >=, >, <=, < or ~ (contains)
  • VALUE: Any string

/prospects?api-key{api_key}&additionalData[]=finance=1 Filter all prospect that have additionalData.finance and is equal to 1.

/prospects?api-key{api_key}&additionalData[]=birthdate<01/01/2000&additionalData[]=birthdate>=01/01/1990 Filter all prospect that have additionalData.birthdate, is greater or equal than 01/01/1990 and lower than 01/01/2000.

/prospects?api-key{api_key}&additionalData[]=style~blue Filter all prospect that have additionalData.style and contains blue string.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

getProspectByParam

Returns a prospect searching by their phone number and/or email. Please notice that even both of these params being optionals, it is necessary to inform at least one of them for the request to be successful processed

Authorizations:
api_key
query Parameters
email
string

Email address string to search for

phoneNumber
string

A phone number string to search for

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "firstName": "John",
  • "emails": [],
  • "phones": [
    ],
  • "account": "string",
  • "claimedBy": "string"
}

getProspectById

Returns an specific prospect by its ID.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

updateProspectById

Update the prospect basic data and/or add a phone and/or email to the prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
archivingReason
string

When the prospect is archived this property contains the code of the reason why it was filed.

firstName
string
lastName
string
phone
string

Phone to add to the prospect

email
string <email>

Email to add to the prospect

label
string

Change Label of the prospect

Responses

Request samples

Content type
application/json
{
  • "archivingReason": "string",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phone": "string",
  • "email": "[email protected]",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

deleteProspect

Delete a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

getProspectAdditionalFieldsById

Returns the available additional fields for a specific prospect by its ID.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

updateAdditionalData

Returns a specific update to the Additional Data of a prospect by its ID.

  {
    "sirenadev_cotti_quoteStatus": "sold",
    "reference": 12345
  }

Where the key of each field is the key of the additional field you want to change. The value is the new value you want to set.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
key
string

The key of the Additional Data

name
string

The name of the Additional Data

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

getProspectInteractions

Returns a filterable list of interactions related to a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

query Parameters
status
string

The status to filter interactions.

createdAfter
string <date-time>

The start date to filter interactions by their creation date.

start
string <date-time>

@deprecated - use createdAfter The start date to filter interactions by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter interactions by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter interactions by their creation date (alias of createdBefore).

via
Array of strings
Items Enum: "walkIn" "sms" "whatsApp" "email" "testDrive" "visit" "phoneCall" "outboundCall" "inboundCall" "facebook"
format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

createInteractionByProspectId

Returns a filterable list of interactions related to a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
type
required
string
Enum: "question" "call" "message" "note"
providerId
string

The ID of the question in the provider.

threadTitle
string

Title of the thread in the provider

threadUrl
string

Url of the thread in the provider

question
string

Question text

answer
string

Answer text to the question, if the status property is "opened" this property will be ignored

delivered
boolean

Check this answer as delivered

cancelReason
string

Reason wherefore the system can not deliver an answer, if the status property is not "cancelled" this property will be ignored

utmSource
string

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

startedAt
string <date-time>

Date and time when the call started.

duration
number

Duration of call in milliseconds.

recordingUrl
string

Complete path to the recorded file URL. Supported audio formats are MP3, WAV and AAC.

content
string

Text message

sender
string

Sender reference

recipient
string

Recipient reference

object

Responses

Request samples

Content type
application/json
{
  • "type": "question",
  • "providerId": "string",
  • "threadTitle": "string",
  • "threadUrl": "string",
  • "question": "string",
  • "answer": "string",
  • "delivered": true,
  • "cancelReason": "string",
  • "utmSource": "google, newsletter4, billboard, ford, bmw",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "duration": 30000,
  • "recordingUrl": "https://s3.amazonaws.com/recordings_2013/d38b5ff0-5752-4cc1-82ba-e1210232c8d5.mp3",
  • "content": "string",
  • "sender": "string",
  • "recipient": "string",
  • "attachment": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

getInteractionById

Returns an interaction by its prospect and interaction IDs.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

interactionId
required
string^[a-z0-9]{24}$

The ID of the interaction.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "agentId": "string",
  • "agent": {
    },
  • "prospectId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "dueAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "proactive": true,
  • "via": "inboundCall",
  • "output": {
    }
}

updateInteractionById

Update interaction using events

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

interactionId
required
string^[a-z0-9]{24}$

The ID of the interaction.

Request Body schema: application/json
type
required
string

Must be "question"

answer
string

Answer text to the question, if the status property is "opened" this property will be ignored

delivered
boolean

Check this answer as delivered

cancelReason
string

Reason wherefore the system can not deliver an answer, if the status property is not "cancelled" this property will be ignored

status
string

Status of the message (pending, sent, received, read, failed)

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "answer": "string",
  • "delivered": true,
  • "cancelReason": "string",
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "agentId": "string",
  • "agent": {
    },
  • "prospectId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "dueAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "status": "string",
  • "proactive": true,
  • "via": "inboundCall",
  • "output": {
    }
}

getInteractions

Returns a filterable list of interactions.

If a limit is not specified, the query will return interactions from the last 31 days

If a limit is not specified, but a date or range of dates are provided, the query will return interactions within the
date or dates specified. A range of dates is considered valid if the range between them is 31 days or less

Invalid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-10-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-06-01T01:00:00.000Z -> INVALID

Valid Examples:
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID
  ?createdAfter=2020-08-01T01:00:00.000Z&createdBefore=2020-09-01T01:00:00.000Z -> VALID

If only one of the dates is provided, the comparison will be made with the present date
Example:

  Assuming that the present date is 2020-10-28T03:00:00.000Z

  ?createdAfter=2020-08-01:T03:00:00.000Z -> INVALID
  ?createdAfter=2020-09-30:T03:00:00.000Z -> VALID
Authorizations:
api_key
query Parameters
before
string^[a-z0-9]{24}$

Limits the results only to the prospects created before the one provided in this parameter (not included)

after
string^[a-z0-9]{24}$

Limits the results only to the prospects created after the one provided in this parameter (not included)

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

agent
string

The id of the agent to filter.

status
string

The status to filter.

createdAfter
string <date-time>

The start date to filter interactions by their creation date.

start
string <date-time>

@deprecated - use createdAfter The start date to filter interactions by their creation date (alias of createdAfter).

createdBefore
string <date-time>

The end date to filter interactions by their creation date.

end
string <date-time>

@deprecated - use createdBefore The end date to filter interactions by their creation date (alias of createdBefore).

via
Array of strings
Items Enum: "walkIn" "sms" "whatsApp" "email" "testDrive" "visit" "phoneCall" "outboundCall" "inboundCall" "facebook"
format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

getProspectQuotes Deprecated

Returns a filterable list of quotes related to a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

query Parameters
status
string
Enum: "pending" "accepted" "rejected"

The status to filter.

createdBefore
string <date-time>

The start date to filter quotes by their creation date.

createdAfter
string <date-time>

The end date to filter quotes by their creation date.

acceptedBefore
string <date-time>

The start date to filter quotes by their accepted date.

acceptedAfter
string <date-time>

The end date to filter quotes by their accepted date.

rejectedBefore
string <date-time>

The start date to filter quotes by their rejected date.

rejectedAfter
string <date-time>

The end date to filter quotes by their rejected date.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

newProspectQuote

Create quote for prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json
status
string
Enum: "pending" "accepted" "rejected"
required
Array of objects (QuoteItem)

Responses

Request samples

Content type
application/json
{
  • "status": "pending",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "prospectId": "string",
  • "status": "pending",
  • "items": [
    ],
  • "total": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "additionalData": { },
  • "finishedAt": "2019-08-24T14:15:22Z"
}

getQuoteById Deprecated

Returns a quote by its prospect and quote IDs.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

quoteId
required
string^[a-z0-9]{24}$

The ID of the quote.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "prospectId": "string",
  • "status": "pending",
  • "items": [
    ],
  • "total": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "additionalData": { },
  • "finishedAt": "2019-08-24T14:15:22Z"
}

updateProspectQuote Deprecated

Update quote for prospect by prospect and quote IDs.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

quoteId
required
string^[a-z0-9]{24}$

The ID of the quote.

Request Body schema: application/json
status
required
string
Enum: "accepted" "rejected"

Responses

Request samples

Content type
application/json
{
  • "status": "accepted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "prospectId": "string",
  • "status": "pending",
  • "items": [
    ],
  • "total": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "rejectedAt": "2019-08-24T14:15:22Z",
  • "acceptedAt": "2019-08-24T14:15:22Z",
  • "additionalData": { },
  • "finishedAt": "2019-08-24T14:15:22Z"
}

getQuotes Deprecated

Returns a filterable list of quotes.

Authorizations:
api_key
query Parameters
before
string^[a-z0-9]{24}$

Limits the results only to the prospects created before the one provided in this parameter (not included)

after
string^[a-z0-9]{24}$

Limits the results only to the prospects created after the one provided in this parameter (not included)

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

status
string
Enum: "pending" "accepted" "rejected"

The status to filter.

createdBefore
string <date-time>

The start date to filter quotes by their creation date.

createdAfter
string <date-time>

The end date to filter quotes by their creation date.

acceptedBefore
string <date-time>

The start date to filter quotes by their accepted date.

acceptedAfter
string <date-time>

The end date to filter quotes by their accepted date.

rejectedBefore
string <date-time>

The start date to filter quotes by their rejected date.

rejectedAfter
string <date-time>

The end date to filter quotes by their rejected date.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

transferProspect

Transfer a Prospect to a group

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json

Define the destination user or group.

group
string (ObjectId) ^[a-z0-9]{24}$
user
string (ObjectId) ^[a-z0-9]{24}$

Responses

Request samples

Content type
application/json
{
  • "group": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

getContactsSelection

Get all contacts for a provided contact selection.

Authorizations:
path Parameters
selectionId
required
string^[a-z0-9]{24}$

The id of the contact selection.

query Parameters
fields
Array of any

The fields to return from prospect. The fields id, status, leads, accountId, account, group, groupId and created will always be returned.

offset
number

The offset number to start pagination starting with 0. Only the offset and the next limit number contacts will be returned.

limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

deprecatedGetArchivingReasons Deprecated

DEPRECATED Use /as-user/archiving-reasons

Authorizations:
api_key
query Parameters
agent
required
string

The agent that has archiving reasons.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Transactional Messaging

Sending transactional messages to prospects (beta)

getChannels

This endpoint returns the channels (communication channels) available in the scope of the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getChannelsByProspectId

Given an ProspectID, this endpoint returns the channels (communication channels) available for that prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

sendTemplateMessage

Send a transactional template message to a prospect

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: application/json
key
required
string

Template key

object

Optional parameters for overriding template parameters. The empty variables must not contain four consecutive spaces, carriage return, new line or tabulations. More information here: https://developers.facebook.com/docs/whatsapp/message-templates/creation

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "parameters": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Conversational Messaging

Sending conversational messages to prospects (beta)

getOrdersByProspect

Returns a filterable list of orders

Authorizations:
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

query Parameters
limit
number

The maximum number of items that must be returned (A multiple number of 100 and no more than 1000 is recommended)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getChannels

This endpoint returns the channels (communication channels) available in the scope of the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getChannelsByProspectId

Given an ProspectID, this endpoint returns the channels (communication channels) available for that prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

sendFile

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: multipart/form-data
required
object

The file to send to the prospect

Responses

Request samples 

var request = require('request');
var fs = require('fs');
var options = {
  'method': 'GET',
  'url': 'https://conversion.zenvia.com/v1/prospect/${prospectId}/messaging/${channel}/send-file?api-key=${apiKey}',
  'headers': {
  },
  formData: {
    'file': {
      'value': fs.createReadStream('/Users/image.jpg'),
      'options': {
        'filename': 'image.jpg',
        'contentType': 'image/jpeg',
        'knownLength': 1024
      }
    }
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

sendMessage

Send a conversational message to a prospect

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

channel
required
string
Enum: "whatsapp" "facebook"

Conversational Channel for sending messages.

Request Body schema: application/json
content
string

Message content

Responses

Request samples

Content type
application/json
{
  • "content": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Act as user

Doing actions as a Zenvia Conversion agent

getTransferable

Returns a list of groups and users the App can transfer prospects to.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "groups": [
    ]
}

labelProspect

Label a prospect.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json

The label that can be used

label
string

Responses

Request samples

Content type
application/json
{
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

getProspectLabels

Returns the prospect labels available to the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getArchivingReasons

Returns the archiving reasons available to the App.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

transferProspectAsUser

Transfer a Prospect to a group or user. The integration (linked to the apiKey) must have a user configured. Also, the integrationType scope must have integration:act-as-user.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json

Define the destination user or group.

group
string (ObjectId) ^[a-z0-9]{24}$
user
string (ObjectId) ^[a-z0-9]{24}$

Responses

Request samples

Content type
application/json
{
  • "group": "string",
  • "user": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "error": "string"
}

archiveProspectAsUser

Archives a Prospect with an archiving reason. The integration (linked to the apiKey) must have a user configured. Also, the integrationType scope must have integration:act-as-user.

Authorizations:
api_key
path Parameters
prospectId
required
string^[a-z0-9]{24}$

The ID of the prospect.

Request Body schema: application/json

The archiving reason that can be used

archivingReason
string

When the prospect is archived this property contains the code of the reason why it was filed.

firstName
string
lastName
string
phone
string

Phone to add to the prospect

email
string <email>

Email to add to the prospect

label
string

Change Label of the prospect

Responses

Request samples

Content type
application/json
{
  • "archivingReason": "string",
  • "firstName": "Jorge",
  • "lastName": "Letona",
  • "phone": "string",
  • "email": "[email protected]",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "account": "string",
  • "accountId": "string",
  • "group": "string",
  • "groupId": "string",
  • "initialGroup": "string",
  • "initialGroupId": "string",
  • "firstName": "Jorge",
  • "label": "warm",
  • "lastName": "Letona",
  • "category": "used",
  • "status": "unclaimed",
  • "nin": [
    ],
  • "userMade": true,
  • "archivingReason": "string",
  • "phones": [
    ],
  • "emails": [],
  • "additionalData": { },
  • "merged": true,
  • "absenceMessage": "string",
  • "leads": [
    ],
  • "agent": {
    },
  • "assigned": "2019-08-24T14:15:22Z",
  • "nextReminder": "2019-08-24T14:15:22Z",
  • "firstContactedAt": "2019-08-24T14:15:22Z",
  • "sentWorkingHourMessage": "2019-08-24T14:15:22Z"
}

Integrations

Getting information from integrations

checkCredentials

Check if API Key exists and if it is enabled.

query Parameters
api-key
required
string

API Key to check.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getIntegration

Returns the active integration

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "providerKey": "string",
  • "groupId": "string",
  • "group": "string",
  • "user": "string",
  • "language": "string",
  • "account": "string",
  • "accountId": "string"
}

getIntegrations

Returns the active integrations in the scope of the API Key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Custom Events

Sending custom events

postEvent

Send a custom event to Zenvia Conversion. Other Apps can receive these events through Webhooks.

Authorizations:
api_key
Request Body schema: application/json
event
required
string
type
required
string (CustomEventType)
Enum: "prospect" "user"

The type of the event

prospectId
string (ObjectId) ^[a-z0-9]{24}$
userId
string (ObjectId) ^[a-z0-9]{24}$
required
object (CustomEventData)

Responses

Request samples

Content type
application/json
{
  • "event": "string",
  • "type": "prospect",
  • "prospectId": "string",
  • "userId": "string",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "messageId": "string",
  • "status": "string"
}

Agents

Getting information from agents

getAgents

Returns the agents from group

Authorizations:
api_key
query Parameters
group
required
string

The groups to get the agents.

active
string

Status of the agent/s.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
application/json
text/csv
[
  • {
    }
]

isAgentWorking

Returns true or false depending on whether the agent is working.

Authorizations:
api_key
path Parameters
agentId
required
string^[a-z0-9]{24}$

The ID of the agent.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getAgentResponseTime

Returns media response time of the agent.

Authorizations:
api_key
path Parameters
agentId
required
string^[a-z0-9]{24}$

The ID of the agent.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

Groups

Getting information from groups

getGroups

Returns the groups that are within the scope of the App

Authorizations:
api_key
query Parameters
parent
string^[a-z0-9]{24}$

The ID of the parent group.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getGroupsByLevel

Returns all immediate children of provided group. If no group is provided then the group where the API Access api-key is located will be assumed as the parent.

Authorizations:
query Parameters
parent
string^[a-z0-9]{24}$

The ID of the parent group.

format
string
Enum: "csv" "json"

An optional flag to force a response format. Note that the API also supports content negotiation and honors the Accept header.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getGroupById

Returns the group that corresponds to the given groupId

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "displayName": "string",
  • "name": "string",
  • "parent": "string",
  • "ancestors": [
    ],
  • "descendants": [
    ],
  • "type": [
    ],
  • "timezone": "string"
}

isGroupWorking

Returns true or false depending if the group has at least one agent working.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

getOnlineAgents

Returns all online agents for the provided group.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

query Parameters
availableAgents
boolean

Filter by available agents.

Responses

Response samples

Content type
application/json
{
  • "officeHours": true,
  • "agents": [
    ]
}

getGroupResponseTime

Returns media response time of the group.

Authorizations:
api_key
path Parameters
groupId
required
string^[a-z0-9]{24}$

The ID of the group.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": "string"
}

Industries

Getting information from available industries

getIndustries

Returns the group industries

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Webhooks

Webhooks allow you to receive notifications to a desired callback URL when something happens in Zenvia Conversion without constantly having to poll the API. Through the API, you can subscribe to the following topics: prospects (contacts), interactions (operations), quotes and agents.

You can review or delete the available subscriptions at any time, directly via the Notifications API.

Retries

If your service has problems handling notifications at any time, we will or will not attempt to re-send failed notifications depending on the case:

  • We will retry up to 20 times in the following cases:

    • Connection failed - If we cannot open an http connection to the provided webhook URL
    • Error codes - If your service responds with any HTTP status code (5xx)
    • Timeout - If your service takes longer than 10 seconds to send back a response

  • We will not retry in the following cases:

    • Response with statusCode < 500 (2xx, 3xx, 4xx)

Successful and Failed Requests

Successful Request Failed Request
Status Code < 400 Timeout or Status Code >= 400

Prospects

Get notified of changes on prospects or when a new prospect is created.

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
whatsAppDueAt
string <date-time> (in case the prospect has an open Whatsapp conversation, this field indicates until when the window to send free messages is open)
facebookDueAt
string <date-time> (in case the prospect has an open Facebook Messenger conversation, this field indicates until when the window to send free messages is open)
updates
Array of objects (List of updates related to this prospect)
{
  • "subscriptionId": "string",
  • "topic": "prospects",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string",
  • "whatsAppDueAt": "2019-08-24T14:15:22Z",
  • "facebookDueAt": "2019-08-24T14:15:22Z",
  • "updates": [
    ]
}
Notification Payload change
New prospect created Type: “created”
The information of a prospect has been edited Type: “updated” "status": "followUp" / “archived”/”unclaimed”/”new”/etc “Updates”: list of changes

Interactions

Events related to existing or new interactions are notified in this topic.

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
Array of objects (interaction related to this notification)
finishedAt
string <date-time>
proactive
boolean
Array of objects (events.output)
via
string (channel used)
Enum: "inboundCall" "outboundCall" "whatsApp" "sms" "email" "walkIn" "visit" "other" "testDrive" "phoneCall" "facebook → FbMessenenger" "webAction" "customApp"
{
  • "subscriptionId": "string",
  • "topic": "interactions",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string",
  • "interaction": [
    ],
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "proactive": true,
  • "output": [
    ],
  • "via": "inboundCall"
}

Interactions can have Type: “created” or Type: “updated”.

List of possible interactions:

  • New message sent to a client
  • New message received from a client
  • A Conversation Toolbar Button is clicked.
  • A client is transferred to another agent
  • New call to a client
  • A note is created on a chat with a client

Quotes (deprecated)

Events related to existing or new quotes are notified in this topic.

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
Array of objects (events.quote)
updates
Array of objects (list of updates related to this quote)
{
  • "subscriptionId": "string",
  • "topic": "quotes",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string",
  • "quote": [
    ],
  • "updates": [
    ]
}
Notification Payload change
Quote created "type": "created"
Quote changes to accepted, rejected or on hold “Status”:”accepted” “Status”:”rejected” “Status”:”pending”

Agents

Events related to agents (requires act-as-user scope).

When you subscribe to this topic, your webhook will receive a request with the following schema:

subscriptionId
string (Subscription Id)
topic
string
type
string (Notification type)
Enum: "updated" "created"
received
string <date-time> (Notification time)
sent
string <date-time> (Notification time)
attempts
number
Array of objects (Prospect Information)
updatedAt
string <date-time> (Date and time of the update)
operationId
string
{
  • "subscriptionId": "string",
  • "topic": "agents",
  • "type": "updated",
  • "received": "2019-08-24T14:15:22Z",
  • "sent": "2019-08-24T14:15:22Z",
  • "attempts": 0,
  • "prospect": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "operationId": "string"
}
Notification Payload change
Prospect created from the agent that is acting on behalf of. "type": "created"
Prospect transfer to the agent that is acting on behalf of. "type": "updated" "updates":

getTopics

Returns information about the available notification topics. Topics can be subscribed to using Subscriptions.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

getActiveSubscriptions

Returns the list of active subscriptions. Note that subscriptions are currently limited to one per group.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

newSubscription

Subscribe to notification topics. Note that subscriptions are currently limited to one per group, and subscribing twice will result in the first subscription being deactivated.

Authorizations:
api_key
Request Body schema: application/json
topics
required
Array of strings

An array of topic names to subscribe to. Use the Notification Topics endpoint to see the available topics.

callbackUrl
required
string

Responses

Request samples

Content type
application/json
{
  • "topics": [
    ],
  • "callbackUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

getActiveSubscriptionById

Returns an active notification subscription by its ID.

Authorizations:
api_key
path Parameters
subscriptionId
required
string^[a-z0-9]{24}$

The ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

deactivateSubscription

Deactivates a subscription by its ID.

Authorizations:
api_key
path Parameters
subscriptionId
required
string^[a-z0-9]{24}$

The ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "topics": [
    ],
  • "callbackUrl": "string"
}

App Lifecycle

Apps should handle the following lifecycle webhooks from Zenvia Conversion. All requests that originate from Zenvia Conversion will include the corresponding Client ID and Secret, and Apps should reject requests with missing or invalid credentials. All requests from Zenvia Conversion include the API Key of the App instance as context.

POST create

Zenvia Conversion will call this endpoint whenever a new App instance is installed. This request will include essential information for the App instance like its API Key and initial state.

The App should store the API Key as it will be needed for future calls to the Zenvia Conversion API. See Authentication.

appId
string
appSecret
string
object
{
  • "appId": "APP_ID",
  • "appSecret": "APP_SECRET'",
  • "integration": {
    }
}

GET form

Apps can design a settings form layout by returning a JSON object with the following schema:

title
string

A title for the form.

description
string

A description for the form. CommonMark syntax MAY be used for rich text representation.

hint
string

A relevant note that the third-party want to communicate to the user. CommonMark syntax MAY be used for rich text representation.

warning
string

An warning that the third-party want to communicate to the user, but that does not prevent submit the form data. CommonMark syntax MAY be used for rich text representation.

error
string

An error that prevents sending the form. CommonMark syntax MAY be used for rich text representation.

required
Array of objects

A list of sections for the form

Array of objects

A list of validation that allow to the third-party to modify the form based on data completed by the user

{
  • "title": "string",
  • "description": "string",
  • "hint": "string",
  • "warning": "string",
  • "error": "string",
  • "sections": [
    ],
  • "validations": [
    ]
}

When the user saves changes to the App settings, Zenvia Conversion will use the names of the inputs as keys and send them to the PUT settings App Lifecycle endpoint.

GET settings

Zenvia Conversion will request the App for a settings object from time to time. Apps can store any relevant settings needed for the App instance.

The keys in the settings object should match with the form inputs names, so they can be edited in the App settings screen by the user.

App response example

{
  "automaticReplyEnabled": true
}

PUT settings

Whenever a user changes the App settings, Zenvia Conversion will send the updated settings object to this endpoint. It is recommended to make a merge with the updated settings since Zenvia Conversion will just send the new ones and not the entire set.

Request payload example

{
  "automaticReplyEnabled": false
}

PUT enabled

Whenever a user disables or enables the App, Zenvia Conversion will notify the App backend of this. Use this to pause or resume the execution of your App instance if applicable.

Any call made to the API by a disabled App will return an error.

enabled
boolean
{
  • "enabled": true
}

PUT api-key

Zenvia Conversion may refresh the App's API Keys at any time, and send the new API Key using this endpoint. Avoid using API Keys that have been refreshed.

newApiKey
string
{
  • "newApiKey": "abc123"
}

DELETE app

Whenever a user deletes the App, Zenvia Conversion will notify the App backend of this and will 'soft' delete it (logical delete)

Response example

{
  "success": true
}

Flow of requests Zenvia Conversion does when creating an App:

  1. GET settings: Without an apiKey. The default settings should be returned in the response. These are used to create an App instance.
  2. GET form: Without an apiKey. The form's structure should be returned in the response.
  3. POST create: With apiKey on the body, Zenvia Conversion will send everything needed to save the App and will expect in return an OK status.
  • From here, any request will have the apiKey.

Extension Points

App developers can leverage the following Extension Points, allowing them to go beyond what is possible to achieve as a Zenvia Conversion user or through the API.

Reports

Apps may add custom reports to the Reports section for managers to use. Users can interact with the App directly through these embedded reports.

Report definition schema:

key
string

Unique identifier for the report.

name
string

Report name and title. Must be localizable.

url
string <uri>

Report URL. May contain placeholders.

{}

Query parameters

Zenvia Conversion will add the following query parameters automatically:

Query Parameter Description Example
sirenaAppId App instance ID 507f191e810c19729de860eb
range Date range of the Report. Can be last-month, this-month, yesterday, today, last30, last7 or custom custom
start Report starting date in YYYY-MM-DD format (only applies for range=custom) 2020-12-01
end Report ending date in YYYY-MM-DD format (only applies for range=custom) 2020-12-31
group ID of the group selected for the report 507f191e810c19729de860ee
parentGroup ID of the group of the user viewing the report 507f191e810c19729de860ef
signature See Request signature below a08116905e92633e4f30eefd1276206b259305c8783642fc5b7f51c089187939

Report URL Placeholders

The report URL may contain placeholders as follows:

https://app.example.com/prospect/${prospect._id}?lang=${group.language}

Supported placeholders:

Placeholder Description Example
user._id ID of the user viewing the report 507f191e810c19729de860ea
user.firstName First name of the user Jorge
user.lastName Last name of the user Letona
user.cellPhone Cell Phone number of the user +15417543010
user.phone Phone number of the user +15417543010
user.email Email of the user [email protected]
group._id ID of the group of the user viewing the report 507f191e810c19729de860ec
group.name Name of the group Sales
group.language Language of the group in ISO 639-1 format en
group.displayName Display name of the group Sales

Conversation Toolbar Buttons

Apps may add custom buttons to the conversation toolbar for agents to use. Once clicked, these buttons open embedded dialogs where the agent can interact with the App directly.

Button definition schema:

key
string

Unique identifier for the button.

name
string

Button name and label. Localizable.

url
string <uri>

Embedded dialog URL. May contain placeholders.

icon
string <data-uri>

Icon in Data URI format. A 64x64 px PNG image is recommended.

{}

Query parameters

Zenvia Conversion will add the following query parameters automatically:

Query Parameter Description Example
sirenaAppId App instance ID 507f191e810c19729de860eb
signature See Request signature below a08116905e92633e4f30eefd1276206b259305c8783642fc5b7f51c089187939

Dialog URL Placeholders

The URL can contain placeholders as follows:

https://app.example.com/prospect/${prospect._id}?lang=${group.language}

Supported placeholders:

Placeholder Description Example
prospect._id ID of the contact whose conversation the button is clicked on 507f191e810c19729de860ea
prospect.firstName First name of the contact John
prospect.lastName Last name of the contact Smith
prospect.phones Phone numbers of the contact. Numbers must be comma separated. +15417543010
prospect.emails Emails of the contact. Numbers must be comma separated. +15417543010
user._id ID of the user viewing the report 507f191e810c19729de860ea
user.firstName First name of the user Jorge
user.lastName Last name of the user Letona
user.cellPhone Cell Phone number of the user 15417543010
user.phone Phone number of the user 15417543010
user.email Email of the user [email protected]
group._id ID of the group 507f191e810c19729de860ea
group.name Name of the group Sales
group.language Language of the group in ISO 639-1 format en
group.displayName Display name of the group Sales
prospect.source Source of the contact Whatsapp
prospect.providerLeadId External id of the contact ABC-123-xyz

Request signature

In order to avoid the forging of requests, Zenvia Conversion adds a signature parameter. To verify it follow these steps:

  1. Get the signature query parameter. Make a copy of the request URL WITHOUT the signature.
  2. Create an HMAC using the URL without signature and the App's Private Key. Node.js example:
    const hmac = crypto.createHmac('sha256', PRIVATE_KEY)
hmac.update(URL)
const EXPECTED_SIGNATURE = hmac.digest('hex')
  3. Compare the signature with EXPECTED_SIGNATURE and reject the request if they don't match.

Prospect Fields

An array of fields to add to the prospect and user entities, respectively. Each field definition contains the following elements:

  • key: Unique identifier for the field.
  • type: Type of field. Can be text, dropdown or date.
  • name: Field name and label. Localizable.
  • hint: Field hint. Localizable.
  • options: Only valid for type: 'dropdown'. An array of options. Each option has the following elements:
    • text: Option display. Localizable.
    • value: Option string value.
  • required: Boolean indicating if the field is required or optional.
  • validationRegex: A regular expression to validate the field values against. Only valid for type: 'text'. Optional.
  • validationError: Error message when validation fails. Use in conjunction with validationRegex. Localizable. Optional.

User Fields

An array of fields to add to the prospect and user entities, respectively. Each field definition contains the following elements:

  • key: Unique identifier for the field.
  • type: Type of field. Can be text, dropdown or date.
  • name: Field name and label. Localizable.
  • hint: Field hint. Localizable.
  • options: Only valid for type: 'dropdown'. An array of options. Each option has the following elements:
    • text: Option display. Localizable.
    • value: Option string value.
  • required: Boolean indicating if the field is required or optional.
  • validationRegex: A regular expression to validate the field values against. Only valid for type: 'text'. Optional.
  • validationError: Error message when validation fails. Use in conjunction with validationRegex. Localizable. Optional.

Localization

All localizable strings need an English variant that will be used by default and may define additional variants for other languages or locales.

They should be objects with the following schema:

fieldName: {
  en: 'Text in English', // mandatory
  es: 'Text in Spanish',
  pt: 'Text in Portuguese'
}