Create or find a contact

Create a contact for the authenticated business, or return the existing one when an identifier you send already belongs to a contact. All fields are optional; any unrecognized field is stored in collected_data.

POST/contacts

Authentication

This endpoint authenticates with your API key sent in the X-API-Key header (ek_live_... format). You can manage your API keys from the Dev Tools section of the dashboard.

Request body

ParameterTypeRequiredDescription
first_nameStringOptionalContact's first name.
last_nameStringOptionalContact's last name.
phone_numberStringOptionalPhone in E.164 format without '+' (digits only, 6-15 chars).
emailStringOptionalContact's email address.
external_idStringOptionalYour own id for this person (for example your user or customer id). Stored on the contact and matched first on later calls.

Example request

bash
curl -X POST "https://api.eclecticlabs.com/api/external/v2/contacts" \
  -H "X-API-Key: ek_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "56912345678",
    "email": "john@doe.com",
    "external_id": "crm-10482",
    "rut": "12345678-9"
  }'

Example response

json
{
  "success": true,
  "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": true,
  "matched_by": "",
  "filled": [],
  "conflicts": []
}

Response fields

  • contact_idUUID of the contact created or found.
  • createdtrue when a new contact was created (201), false when an existing one was returned (200).
  • matched_byHow the existing contact was found: external_id, phone or email. Empty when a contact was created.
  • filledIdentifiers the existing contact lacked and were added from this request: email, phone, external_id.
  • conflictsOther contacts your identifiers point at, each with its contact_id and the matched_by identifier. Empty when everything matched the same contact.

Notes

  • Before creating, the contact is looked up by external_id, then phone_number, then email (case-insensitive). The first match is returned with created: false, its missing identifiers are filled in and the extra fields are merged into its collected_data.
  • Phones match with or without the mobile 9 (Chile, Argentina) and the legacy 1 (Mexico). A Chilean number sent without the 9 is stored with it, so the person's WhatsApp messages land on the same contact.
  • When the identifiers belong to different contacts nothing is merged: the first match is returned and the others are listed in conflicts. Decide yourself and call POST /contacts/merge if they are the same person.
  • Any additional field is stored in the contact's collected_data.
  • Possible errors: 400 (validation), 401 (invalid or missing API key), 500 (internal error).