CRM

Create /leads

POST/api/v1/leads

Creates a record. Requires a read-write key with a responsible user; send Idempotency-Key so you can retry without duplicates. Creation fires the account's webhooks and automations, just like the screen.

Today the API records the created lead's source as API.

Key scope

Requires a read-write key (READ_WRITE) with a responsible user.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	yes	Bearer followed by the key. Alternative: X-API-Key header.
`Idempotency-Key`	header	string	no	Idempotency key (kept 24h, body up to 2 MB). Same key + same body returns the stored original response; same key + different body gets 409; same key while the first run is still going gets 409 with Retry-After: 5. A 5xx does not freeze the key.

Request body

Name	Type	Required	Description
`nome`	string	yes	Name.
`email`	string	no	E-mail.
`telefone`	string	no	Phone.
`origem`	string	no	Lead source.
`campanha`	string	no	Source campaign.

Response fields

Name	Type	Description
`id`	integer	Record identifier. Use it in by-id calls.
`codigo`	integer	Record code as shown on screen.
`nome`	string	Name.

Status codes

HTTP	Description
201	Created
401	Missing or invalid key
403	Key without write scope

Error messages

HTTP	Message (erro field)	When it happens
401	`chave de API ausente ou inválida`	No key header, revoked key or typo.
401	`chave sem empresa vinculada`	The key exists but is not linked to an account. Create another one in Settings › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	The call reached the demo account, where the public API is turned off.
403	`identidade da chave de API irregular`	The account refuses keys with irregular identity (deactivated person or ownerless key). The body brings motivo and comoResolver.
429	`limite de requisições excedido (120/min)`	The key went over its per-minute limit. Wait for Retry-After.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Write with a read-only key.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	The write key has no responsible user: without authorship nothing is saved.
400	`Idempotency-Key é obrigatória em escrita desde 2026-12-01 (aviso publicado em 2026-09-01): sem ela, um retry de rede cria o registro duas vezes. Envie um valor único por operação no cabeçalho Idempotency-Key.`	Write without Idempotency-Key after the mandatory date.
409	`Idempotency-Key já usada com um corpo DIFERENTE — gere uma chave nova por operação`	The same Idempotency-Key came with another body.
409	`requisicao com esta Idempotency-Key ainda em processamento — aguarde e repita`	The same Idempotency-Key arrived while the first call was still running. Retry after Retry-After.
400	`JSON inválido`	The body is not a valid JSON object.
422	`nome é obrigatório`	nome is missing or empty.
422	`não foi possível criar: {detalhe}`	The write was refused (for example, a value longer than the field allows). Details in the message.

Request example

cURL

curl -X POST "https://tenka.app.br/api/v1/leads" \
  -H "Authorization: Bearer $TENKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "nome": "Comercial Aurora Ltda",
  "email": "contato@exemplo.com",
  "telefone": "+55 11 99999-0000"
}'

JavaScript

const response = await fetch("https://tenka.app.br/api/v1/leads", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + TENKA_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    "nome": "Comercial Aurora Ltda",
    "email": "contato@exemplo.com",
    "telefone": "+55 11 99999-0000"
  })
});
const data = await response.json();
if (!response.ok || data.erro) throw new Error(response.status + " " + data.erro);
console.log(data);

Python

import os
import uuid
import requests

response = requests.post(
    "https://tenka.app.br/api/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['TENKA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "nome": "Comercial Aurora Ltda",
      "email": "contato@exemplo.com",
      "telefone": "+55 11 99999-0000"
    },
    timeout=30,
)
data = response.json()
if not response.ok or "erro" in data:
    raise RuntimeError(f"{response.status_code} {data.get('erro')}")
print(data)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create("https://tenka.app.br/api/v1/leads"))
    .header("Authorization", "Bearer " + System.getenv("TENKA_API_KEY"))
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", java.util.UUID.randomUUID().toString())
    .POST(HttpRequest.BodyPublishers.ofString("""
        {
          "nome": "Comercial Aurora Ltda",
          "email": "contato@exemplo.com",
          "telefone": "+55 11 99999-0000"
        }
        """))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());

using System.Net.Http.Headers;
using System.Text;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("TENKA_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Post, "https://tenka.app.br/api/v1/leads");
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString());
request.Content = new StringContent(@"{
  ""nome"": ""Comercial Aurora Ltda"",
  ""email"": ""contato@exemplo.com"",
  ""telefone"": ""+55 11 99999-0000""
}", Encoding.UTF8, "application/json");
var response = await http.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

PHP

<?php
$ch = curl_init("https://tenka.app.br/api/v1/leads");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TENKA_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => '{
  "nome": "Comercial Aurora Ltda",
  "email": "contato@exemplo.com",
  "telefone": "+55 11 99999-0000"
}',
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($body, true);
echo $status . " " . $body;

Node (SDK)

// SDK generated from the contract — download at https://tenka.app.br/api/v1/sdk/tenka.js
import { Tenka } from "./tenka.js";

const tenka = new Tenka(process.env.TENKA_API_KEY, "https://tenka.app.br/api/v1");
const data = await tenka.postLeads({}, {
    "nome": "Comercial Aurora Ltda",
    "email": "contato@exemplo.com",
    "telefone": "+55 11 99999-0000"
  }, crypto.randomUUID());
console.log(data);

Response example

201 · application/json

{
  "id": 123,
  "codigo": 1042,
  "nome": "Comercial Aurora Ltda"
}

Generated from OpenAPI contract v1.2.0, the same one openapi.json publishes. openapi.json