Saltar al contenido principal
API docs by Redocly

Ventia CRM API (1.0)

Download OpenAPI specification:Download

First steps

Welcome to the documentation for the public API of Ventia CRM module.

Ventia has differents module and the module who have available API are:

  • CRM
  • Sales Manager
  • People

Authentication

All request on Ventia require a valid API Key passed as query string on the request.

Example:

https://api.getventia.com/api/v1.0/contact?api-key=AAAAAAA-BBBBBBB-CCCCCCC-DDDDDDD

Authentication error response

If an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.

Rate and usage limits

To ensure the best possible performance and availability for all our users, we have implemented rate and usage limits on our API. These limits are designed to prevent any single user from consuming excessive resources and negatively impacting the experience for others.

Maximum Requests Per Minute

Our API enforces a maximum limit of 200 requests per minute (RPM). This means that you can make up to 200 requests within a one-minute time frame. If you exceed this limit, your requests will be throttled, and you will receive an HTTP 429 "Too Many Requests" response.

Please note that the rate limit is applied on a per-account basis, so all API keys associated with a single account will share the same limit.

Pagination

When fetching a endpoint who has a list, pagination is used by default.

To controll the pagination use on the url on the querystring :

?page=0 to controll the page you'r viewing

?limit=100 to controll the page size

Need some help?

If you need support you can use our support via email or support chat on Ventia

Contact

List contacts

Authorizations:
apiKey

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Get one contact

Authorizations:
apiKey
path Parameters
idcontact
required
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "_id": "621e8a5463c02a8bd532ff8c",
  • "company": "609b3cff61ffd5f1e446d234",
  • "firstName": "Agustin",
  • "lastName": "Suarez",
  • "origin": "local",
  • "phones": [
    ],
  • "agent": "6234da84259c59d9a555c498",
  • "agentAssigned": "2022-03-01T21:04:20.611Z",
  • "archivingReason": "",
  • "status": "closed",
  • "emails": [ ],
  • "detail": "",
  • "createdAt": "2022-03-01T21:04:20.617Z",
  • "updatedAt": "2022-05-20T16:00:00.004Z",
  • "__v": 0,
  • "lastInteraction": "2022-05-20T16:00:00.004Z",
  • "archivingReasonText": "",
  • "agentFullName": "Agente"
}

Modify contact

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
firstName
required
string
lastName
required
string
emails
required
Array of strings
phones
required
Array of strings
detail
required
string
origin
required
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "Agustin",
  • "lastName": "Suarez",
  • "emails": [
    ],
  • "phones": [
    ],
  • "detail": "",
  • "origin": "store"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "_id": "621e8a5463c02a8bd532ff8c",
  • "company": "609b3cff61ffd5f1e446d234",
  • "firstName": "Agustin",
  • "lastName": "Perez",
  • "origin": "local",
  • "phones": [
    ],
  • "archivingReason": "",
  • "status": "new",
  • "emails": [
    ],
  • "detail": "",
  • "createdAt": "2022-03-01T21:04:20.617Z",
  • "updatedAt": "2023-05-23T20:20:25.420Z",
  • "__v": 1,
  • "lastInteraction": "2023-05-23T20:20:25.418Z",
  • "archivingReasonText": "",
  • "assignedGroups": [ ],
  • "attention": "not_actions",
  • "channels": [ ],
  • "databaseUploded": false,
  • "reminder": "2023-05-23T20:25:02.561Z"
}

List interactions from one contact

Authorizations:
apiKey
path Parameters
idcontact
required
string

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Create contact

Authorizations:
apiKey
Request Body schema: text/plain
required
string

Responses

Request samples

Content type
text/plain
{
    "firstName": "Agustin",
    "lastName": "Suarez",
    "emails": ["agustin@example.com"],
    "phones": ["+59897444666"],
    "detail": "",
    "origin": "store"
}

}

Response samples

Content type
application/json; charset=utf-8
{
  • "company": "609b3cff61ffd5f1e446d234",
  • "firstName": "Agustin",
  • "lastName": "Suarez",
  • "origin": "local",
  • "originText": "Local",
  • "phones": [
    ],
  • "agent": "609d8512ee84d2388bde2353",
  • "agentFullName": "Agent Name",
  • "firstAgent": "609d8512ee84d2388bde2353",
  • "firstAgentFullName": "Agent Name",
  • "agentAssigned": "2023-05-18T17:55:17.559Z",
  • "archivingReason": "",
  • "archivingReasonText": "",
  • "status": "new",
  • "attention": "not_actions",
  • "emails": [
    ],
  • "detail": "",
  • "stats": {
    },
  • "createdCoords": {
    },
  • "contactLocation": {
    },
  • "databaseUploded": false,
  • "channels": [ ],
  • "assignedGroups": [ ],
  • "_id": "64666685696358053f46c33a",
  • "lastInteraction": "2023-05-18T17:55:17.560Z",
  • "createdAt": "2023-05-18T17:55:17.561Z",
  • "updatedAt": "2023-05-18T17:55:17.561Z",
  • "__v": 0
}

Create lead

Add Lead

This endpoint allows you to create campaing leads.

Campaing leads are created as contacts if they dosen't exist on the database, but if it exists, ventia notifiys the agent owner of the contact with a note.

Authorizations:
apiKey
Request Body schema: application/json
required
firstName
required
string
lastName
required
string
emails
required
Array of strings
phones
required
Array of strings
detail
required
string
origin
required
string
agent
required
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "Agustin",
  • "lastName": "Suarez",
  • "emails": [
    ],
  • "phones": [
    ],
  • "detail": "",
  • "origin": "local",
  • "agent": "609d8512ee84d2388bde2353"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "company": "609b3cff61ffd5f1e446d234",
  • "firstName": "Agustin",
  • "lastName": "Suarez",
  • "origin": "local",
  • "originText": "Local",
  • "phones": [
    ],
  • "agent": "609d8512ee84d2388bde2353",
  • "agentFullName": "Agent Name",
  • "firstAgent": "609d8512ee84d2388bde2353",
  • "firstAgentFullName": "Agent Name",
  • "agentAssigned": "2023-05-18T17:55:17.559Z",
  • "archivingReason": "",
  • "archivingReasonText": "",
  • "status": "new",
  • "attention": "not_actions",
  • "emails": [
    ],
  • "detail": "",
  • "stats": {
    },
  • "createdCoords": {
    },
  • "contactLocation": {
    },
  • "databaseUploded": false,
  • "channels": [ ],
  • "assignedGroups": [ ],
  • "_id": "64666685696358053f46c33a",
  • "lastInteraction": "2023-05-18T17:55:17.560Z",
  • "createdAt": "2023-05-18T17:55:17.561Z",
  • "updatedAt": "2023-05-18T17:55:17.561Z",
  • "__v": 0
}

Interactions

List interactions

Authorizations:
apiKey

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Create note

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
body
required
string

Responses

Request samples

Content type
application/json
{
  • "body": "He will buy"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "note": {
    }
}

Archive contact

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
reason
required
string

Responses

Request samples

Content type
application/json
{
  • "reason": "sintrabajo"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "archive": {
    }
}

Transfer contact

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
to
required
string

Responses

Request samples

Content type
application/json
{
  • "to": "6234da84259c59d9a555c498"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "transfer": {
    }
}

Create message

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
text
required
string
channel
required
string

Responses

Request samples

Content type
application/json
{
  • "text": "Hi client",
  • "channel": "wpp"
}

Create reminder

Authorizations:
apiKey
path Parameters
idcontact
required
string
Request Body schema: application/json
required
reminderDate
required
string

Responses

Request samples

Content type
application/json
{
  • "reminderDate": "2023-05-23T20:25:02.561Z"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "message": "Reminder created",
  • "reminder": {
    }
}

Users

Get users

Authorizations:
apiKey

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Create user

Creates a new user in the system with the provided details.

Authorizations:
apiKey
Request Body schema: application/json
required
name
required
string [ 2 .. 32 ] characters

The user's first name

lastname
required
string non-empty

The user's last name

email
required
string <email>

The user's email address

password
required
string >= 4 characters

The user's password

phone_work
string or null

The user's work phone number

roles
Array of strings
Default: ["user"]
Items Enum: "user" "comercial" "super"

The user's roles

Responses

Request samples

Content type
application/json
{
  • "name": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "password": "mySecurePassword123",
  • "phone_work": "+1234567890",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "64b7654c3f3ae9b9d1e7c5d8",
  • "name": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "phone_work": "+1234567890",
  • "group": "64b7654c3f3ae9b9d1e7c5d7",
  • "roles": [
    ],
  • "firstLogin": true
}

Get a user by ID

Retrieves a user by the id parameter. Only active users belonging to the authenticated group or its descendant groups are returned.

Authorizations:
apiKey
path Parameters
id
required
string

The ID of the user to retrieve

header Parameters
X-API-KEY
required
string

The API key used to authenticate the request

Responses

Response samples

Content type
application/json
{
  • "_id": "64b7654c3f3ae9b9d1e7c5d8",
  • "name": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "phone_work": "+1234567890",
  • "firstLogin": "2024-01-01T12:00:00Z",
  • "group": "64b7654c3f3ae9b9d1e7c5d7",
  • "roles": [
    ]
}

Partially update an existing user

Updates one or more fields of a user identified by the id parameter.

Authorizations:
apiKey
path Parameters
id
required
string

The ID of the user to be updated

Request Body schema: application/json
required
name
string [ 2 .. 32 ] characters

The user's first name

lastname
string non-empty

The user's last name

email
string <email>

The user's email address

phone_work
string or null

The user's work phone number

roles
Array of strings
Items Enum: "user" "comercial" "super"

The user's roles

Responses

Request samples

Content type
application/json
{
  • "name": "Jane",
  • "lastname": "Doe",
  • "email": "jane.doe@example.com",
  • "phone_work": "+9876543210",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "64b7654c3f3ae9b9d1e7c5d8",
  • "name": "Jane",
  • "lastname": "Doe",
  • "email": "jane.doe@example.com",
  • "phone_work": "+9876543210",
  • "group": "64b7654c3f3ae9b9d1e7c5d7",
  • "roles": [
    ]
}

Fully update or replace an existing user

Replaces the entire user identified by the id parameter.

Authorizations:
apiKey
path Parameters
id
required
string

The ID of the user to be updated

Request Body schema: application/json
required
name
string [ 2 .. 32 ] characters

The user's first name

lastname
string non-empty

The user's last name

email
string <email>

The user's email address

phone_work
string or null

The user's work phone number

roles
Array of strings
Items Enum: "user" "comercial" "super"

The user's roles

Responses

Request samples

Content type
application/json
{
  • "name": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "phone_work": "+1234567890",
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "64b7654c3f3ae9b9d1e7c5d8",
  • "name": "John",
  • "lastname": "Doe",
  • "email": "john.doe@example.com",
  • "phone_work": "+1234567890",
  • "group": "64b7654c3f3ae9b9d1e7c5d7",
  • "roles": [
    ]
}

Groups

Get groups

Authorizations:
apiKey

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Sales

Get sales data

Retrieves sales data filtered with pagination.

Authorizations:
apiKey
query Parameters
page
integer >= 1
Default: 1

Page number for pagination.

limit
integer [ 1 .. 100 ]
Default: 50

Number of items per page.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a new sale

Creates a new sale record in the system.

Authorizations:
apiKey
Request Body schema: application/json
required
status
required
string

The status of the sale to match in system.

ticket_id
required
string

ID of the ticket.

ticket_sale_id
string

ID of the ticket sale.

date_sale
string <date>

Sale date. Accepted format: yyyy/mm/dd or yyyy-mm-dd.

date
string <date>

Sale date. Accepted format: yyyy/mm/dd or yyyy-mm-dd.

type
string

Type of sale.

phone
required
string

Customer's phone number.

name
string

Customer's name.

gov_id
string

Customer's government ID.

user
required
string

ID of the user making the sale.

Responses

Request samples

Content type
application/json
{
  • "status": "SOLD",
  • "ticket_id": "ticket-5678",
  • "ticket_sale_id": "sale-5678",
  • "date_sale": "2024-02-24",
  • "date": "2024-02-24",
  • "type": "online",
  • "phone": "+12345678900",
  • "name": "John Doe",
  • "gov_id": "12345678",
  • "user": "abcd1234efgh5678ijkl9012"
}

Response samples

Content type
application/json
{
  • "ticket_id": "ticket-5678",
  • "ticket_sale_id": "sale-5678",
  • "date": "2024-02-24T15:00:00.000Z",
  • "date_sale": "2024-02-24T15:00:00.000Z",
  • "name": "John Doe",
  • "phone": "+12345678900",
  • "secondary_phones": [ ],
  • "gov_id": "12345678",
  • "status": "SOLD",
  • "status_lock": false,
  • "sold": true,
  • "cancel": false,
  • "lock": false,
  • "user": "abcd1234efgh5678ijkl9012",
  • "user_string": "John Doe",
  • "user_lock": false,
  • "user_edit": false,
  • "company": "abcd1234efgh5678ijkl9012",
  • "importation": "Public API",
  • "value": 0,
  • "remove_from_goal": false,
  • "comissions": [
    ],
  • "_id": "abcd1234efgh5678ijkl9012",
  • "createdAt": "2024-10-23T20:02:13.887Z",
  • "updatedAt": "2024-10-23T20:02:13.887Z",
  • "__v": 0
}

Get sale by ID

Retrieves a specific sale by its unique ID.

Authorizations:
apiKey
path Parameters
id
required
string

The unique ID of the sale.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "company": "string",
  • "user": {
    },
  • "createdAt": "2019-08-24T14:15:22Z"
}

Modify sale by ID

Updates fields of an existing sale by its unique ID.

Authorizations:
apiKey
path Parameters
id
required
string

The unique ID of the sale to be updated.

Request Body schema: application/json
required
status
string

Status of the sale.

date_sale
string <date>

Date when the sale occurred.

user
string

ID of the user associated with the sale.

Responses

Request samples

Content type
application/json
{
  • "status": "sold",
  • "date_sale": "2024-01-01",
  • "user": "60d0fe4f5311236168a109ca"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "user": "string",
  • "user_string": "string",
  • "status": "string",
  • "date_sale": "2019-08-24",
  • "sold": true
}

Upsert sale by ID

Updates an existing sale by its unique ID or creates a new one if it doesn't exist.

Authorizations:
apiKey
path Parameters
id
required
string

The unique ID of the sale to be upserted.

Request Body schema: application/json
required
status
string

Status of the sale.

ticket_id
string

ID of the ticket related to the sale.

ticket_sale_id
string

Optional ID for ticket sale.

date_sale
string <date>

Optional sale date.

date
string <date>

Optional date of the sale record.

type
string

Type of sale.

phone
string

Phone number associated with the sale.

name
string

Optional name associated with the sale.

product
string

Optional product related to the sale.

gov_id
string

Optional government ID associated with the sale.

user
string

ID of the user responsible for the sale.

importation
string

Optional importation method.

Responses

Request samples

Content type
application/json
{
  • "status": "sold",
  • "ticket_id": "123456",
  • "date_sale": "2024-01-01",
  • "phone": "+1234567890",
  • "user": "60d0fe4f5311236168a109ca"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "status": "string",
  • "date_sale": "2019-08-24",
  • "phone": "string",
  • "name": "string",
  • "user": "string",
  • "product": "string"
}

LeadEntry

Create a new lead entry

Validates and creates a new lead entry based on the received data.

Authorizations:
apiKey
path Parameters
code
required
string

The unique code of the lead entry form

Request Body schema: application/json
required
firstName
string
lastName
string
Default: ""
phones
Array of strings
emails
Array of strings <email> [ items <email > ]
Default: []
detail
string
Default: ""
action_id
string
object
Default: {}

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "",
  • "phones": [
    ],
  • "emails": [ ],
  • "detail": "",
  • "action_id": "string",
  • "additionalData": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "phones": [
    ],
  • "emails": [
    ],
  • "detail": "string",
  • "action_id": "string",
  • "additionalData": {
    }
}

WhatsApp Official

Send message

This documentation provides guidelines for sending messages through the official WhatsApp API, with Ventia acting as an intermediary. It covers the supported message types, integration details, and best practices to ensure a seamless messaging experience. The supported message types align with those in the Facebook API. For more details, refer to the official Facebook documentation at https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages/. Some message types are still in development, so please check the documentation below to verify the available types.

Authorizations:
apiKey
path Parameters
channelId
required
string

Unique identifier of the communication channel as registered on the Ventia platform.

contactId
required
string

Unique identifier of the recipient contact as registered on the Ventia platform.

Request Body schema: application/json
required
preview_url
string

Indicates whether a preview of the link will be generated in the WhatsApp message. If present and enabled, WhatsApp will attempt to fetch a preview of the link's content.

required
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true,
  • "messaging_product": "whatsapp",
  • "contacts": [
    ],
  • "messages": [
    ]
}

Webhooks

Get webhooks

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "result": [],
  • "paging": {
    }
}

Create webhook

Authorizations:
apiKey
Request Body schema: application/json
required
active
required
boolean

Indicates whether the configuration is active.

name
required
string [ 1 .. 64 ] characters

Identifier name. Must be between 1 and 255 characters.

callbackUrl
required
string^https://.*

Secure URL (HTTPS) where related events will be sent.

topics
Array of strings
Items Enum: "interactions.official_whatsapp" "interactions.official_whatsapp_statuses"

List of subscribed topics. Only specific values are allowed.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true,
  • "id": "67bca48d5fc32659c854f83c"
}

Update webhook by ID

Authorizations:
apiKey
path Parameters
id
required
string

Unique identifier of the webhook.

Request Body schema: application/json
required
active
boolean
name
string [ 1 .. 64 ] characters
callbackUrl
string
topics
Array of strings
Items Enum: "interactions.official_whatsapp" "interactions.official_whatsapp_statuses"

Responses

Request samples

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

Response samples

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

Get webhook by ID

Authorizations:
apiKey
path Parameters
id
required
string

Unique identifier of the webhook.

Responses

Response samples

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

Delete webhook by ID

Authorizations:
apiKey
path Parameters
id
required
string

Unique identifier of the webhook.

Responses

Response samples

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