Crear contacto

POSThttps://api.bydomu.com/v1/contacts

Esta referência é gerada a partir do código da API, por isso as descrições estão em espanhol. Nomes, parâmetros e exemplos são iguais em qualquer idioma.

Crea un contacto en el CRM. El teléfono es único por organización: si ya existe responde 409 DUPLICATE. Respeta el tope de contactos del plan (403 PLAN_LIMIT_REACHED). El dueño por defecto es quien creó la API key. La respuesta no incluye las etiquetas asignadas con tags.

Permissão

contacts:write

Chaves

Só secreta (de um servidor)

Cabeçalhos

X-API-Keystringobrigatório

Sua chave secreta.

Idempotency-Keystring

Clave única de la operación (8-128 caracteres de [a-zA-Z0-9._:-]). Un reintento con la misma clave y el mismo cuerpo devuelve la respuesta original sin repetir la operación. Vive 24 horas. · 8–128 chars

Corpo (JSON)

firstNamestringobrigatório

2–100 chars

lastNamestring

≤ 100 chars

emailstring

phonestringobrigatório

phone2string

sourcestring

WHATSAPPMETROCUADRADOFINCARAIZWEBSITEREFERRALWALK_INSOCIAL_MEDIAPHONEOTHER · default="OTHER"

statusstring

NEWCONTACTEDQUALIFIEDNEGOTIATINGWONLOSTINACTIVE · default="NEW"

typestring

CLIENTOWNERBOTH · default="CLIENT"

documentTypestring

CCCENITPASSPORTDNIRUCCURPRFCOTHER · nullable

documentNumberstring

≤ 50 chars

scoreinteger

default=0 · 0–100 · nullable

notesstring

≤ 5000 chars

budgetnumber

≥ 0 · nullable

currencystring

COPUSDEURMXNBRLARSBOBCADCLPCRCCUPDOPGBPGTQHNLNIOPENPYGUYUVES · default="COP"

lookingForstring

≤ 500 chars

preferredTypestring

APARTMENTHOUSEOFFICECOMMERCIALLANDWAREHOUSEROOMFARMOTHER · nullable

preferredCitystring

≤ 100 chars

preferredNeighborhoodstring

≤ 100 chars

minBedroomsinteger

≥ 0 · nullable

minBathroomsinteger

≥ 0 · nullable

minAreanumber

≥ 0 · nullable

preferredTransactionTypestring

SALERENTBOTH · nullable

ownerIdstring

tagsstring[]

Etiquetas por nombre. Se crean las que no existan y se AGREGAN a las que ya tenga el contacto.

Respostas

201Contacto creado

400Datos inválidos: el cuerpo o la query no cumplen el esquema, o `Idempotency-Key` está mal formada.

401UNAUTHORIZED · Clave faltante, inválida, desactivada o vencida.

402PAYMENT_REQUIRED · Cuenta en modo solo lectura: se rechaza toda mutación.

403FORBIDDEN · La clave no puede usar esta operación: falta el scope, es una secreta en el navegador, el nivel de la cuenta no la permite, está suspendida o se alcanzó un tope del plan.

404NOT_FOUND · El recurso no existe en la organización.

409DUPLICATE · Choca con un dato existente o con el estado actual, o la `Idempotency-Key` ya se usó con otro cuerpo o sigue en curso.

429RATE_LIMITED · Límite de peticiones excedido: el de la clave (`RATE_LIMITED`), el de escrituras de la organización (`TENANT_RATE_LIMITED`) o bloqueo temporal de la IP por claves inválidas.

500INTERNAL_ERROR · Error interno del servidor.

curl -X POST "https://api.bydomu.com/v1/contacts" \ -H "X-API-Key: $BYDOMU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "firstName": "María", "lastName": "González", "phone": "+573001234567", "email": "[email protected]", "source": "WEBSITE", "type": "CLIENT", "budget": 350000000, "preferredType": "APARTMENT", "preferredCity": "Bogotá", "tags": [ "VIP", "Inversionista" ] }'

const res = await fetch("https://api.bydomu.com/v1/contacts", { method: "POST", headers: { "X-API-Key": process.env.BYDOMU_API_KEY, "Content-Type": "application/json", }, body: JSON.stringify({ "firstName": "María", "lastName": "González", "phone": "+573001234567", "email": "[email protected]", "source": "WEBSITE", "type": "CLIENT", "budget": 350000000, "preferredType": "APARTMENT", "preferredCity": "Bogotá", "tags": [ "VIP", "Inversionista" ] }), }); const data = await res.json();

import os, requests r = requests.post( "https://api.bydomu.com/v1/contacts", headers={"X-API-Key": os.environ["BYDOMU_API_KEY"]}, json={ "firstName": "María", "lastName": "González", "phone": "+573001234567", "email": "[email protected]", "source": "WEBSITE", "type": "CLIENT", "budget": 350000000, "preferredType": "APARTMENT", "preferredCity": "Bogotá", "tags": [ "VIP", "Inversionista" ] } ) data = r.json()

{ "data": { "id": "clx1con001", "code": "C-0107", "firstName": "María", "lastName": "González", "email": "[email protected]", "phone": "+573001234567", "phone2": "+573109876543", "source": "WHATSAPP", "status": "NEW", "type": "CLIENT", "documentType": "CC", "documentNumber": "1020304050", "score": 75, "notes": "Busca apartamento cerca al trabajo.", "budget": "350000000.00", "currency": "COP", "lookingFor": "Apartamento de 3 habitaciones", "preferredType": "APARTMENT", "preferredCity": "Bogotá", "preferredNeighborhood": "Chapinero", "minBedrooms": 3, "minBathrooms": 2, "minArea": 70, "preferredTransactionType": "SALE", "subscribedToAlerts": true, "whatsappOptIn": true, "marketingOptIn": false, "ownerId": "clx1usr001", "createdAt": "2026-01-15T14:30:00.000Z", "updatedAt": "2026-09-20T09:15:00.000Z", "owner": { "id": "clx1usr001", "firstName": "Carlos", "lastName": "Rodríguez" } } }