Crear contacto

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

This reference is generated from the API’s code, so descriptions are in Spanish. Names, parameters and examples are the same in every language.

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.

Permission

contacts:write

Keys

Secret only (server-side)

Headers

X-API-Keystringrequired

Your secret key.

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

Body (JSON)

firstNamestringrequired

2–100 chars

lastNamestring

≤ 100 chars

emailstring

phonestringrequired

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.

Responses

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" } } }