The Ventia API lets you manage contacts, leads, interactions, sales, users and WhatsApp Business messages from your own systems. It is a REST API that accepts and returns JSON.

Base URL

https://api.getventia.com/api/v1.0

All endpoints in this reference are relative to this URL.

Authentication

Every request needs an API key in the Authorization header, using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

Status	Meaning
401 Unauthorized	The API key is missing, malformed or invalid.
403 Forbidden	The key is valid, but the API feature is not enabled for your company. Contact Ventia support to enable it.

Keep your API key secret. Call the API from your server, never from a browser or mobile app.

Your first request

List the first contact in your account:

curl "https://api.getventia.com/api/v1.0/contacts?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "_id": "621e8a5463c02a8bd532ff8c",
    "firstName": "Agustin",
    "lastName": "Suarez",
    "phones": ["+59897123678"],
    "emails": [],
    "status": "closed",
    "agent": "6234da84259c59d9a555c498",
    "createdAt": "2022-03-01T21:04:20.617Z",
    "updatedAt": "2022-05-20T16:00:00.004Z"
  }
]

Errors

The API uses standard HTTP status codes. Errors return a JSON body with an error message:

{ "error": "Contact not found" }

Status	Meaning
400 Bad Request	The request is invalid, for example a missing field or a malformed ID.
401 Unauthorized	The API key is missing or invalid.
403 Forbidden	The API feature is not enabled for your company.
404 Not Found	The resource does not exist.
409 Conflict	The request conflicts with an existing resource.
422 Unprocessable Entity	The request is well formed but cannot be processed.
429 Too Many Requests	You exceeded the rate limit.
500 Internal Server Error	Something went wrong on our side.

Rate limits

You can make up to 200 requests per minute. The limit applies per account, so all API keys for the same account share it.

Requests over the limit receive 429 Too Many Requests. Wait before retrying, and back off further if you keep receiving it.

Pagination

List endpoints are paginated. Control the page with query parameters:

Parameter	Description
page	Page to return, starting at 1. Defaults to 1.
limit	Items per page. The default and maximum vary by endpoint; see each endpoint's reference.

Paginated responses include these headers:

Header	Description
X-Total-Count	Total number of records matching the query.
X-Total-Pages	Total number of pages.
X-Current-Page	Page returned.
X-Per-Page	Page size.

Versioning

The API version is part of the base URL (v1.0). Breaking changes will be released under a new version, so your integration keeps working on v1.0.

Support

Need help? Email us at soporte@getventia.com.