Back to API docs

apicreatecontact JSON request body single or bulk copy/paste docs

POST /api/createcontact creates a new contact, or updates an existing contact when code matches. POST /api/editcontact updates an existing contact by id and supports the same core fields and meta fields.

Top-level JSON fields

key

string, required

Your API key.

contacts

array of objects, optional

If provided, the endpoint creates or updates multiple contacts in one request. Each item in contacts[] uses the same fields as the single-contact payload, just without the top-level key.

If contacts is missing, the request is treated as a single contact payload where fields like name, code, and email are top-level.

Contact Fields

name

string, required

Company/client name. Empty names are rejected.

code

string, optional

Company/client code. When provided and an existing contact has the same code, that contact is updated instead of creating a duplicate.

phone, email, address, person

string, optional

Saved directly to the contacts table.

manager, lead, lead_data, zoho_id

optional

Advanced fields saved directly to the contacts table when supplied.

Contact Meta Fields

vat, website, city

string, optional

Legacy convenience fields saved to contact_meta.

meta or metas

object, optional

Additional custom contact metadata. Keys become contact_meta.field, values become contact_meta.value.

{
  "meta": {
    "vat": "LT123456789",
    "website": "https://example.com",
    "city": "Vilnius",
    "payment_terms": "14 days"
  }
}

If the same meta field already exists for the contact, it is updated. Otherwise it is created.

Single Contact Example

{
  "key": "YOUR_API_KEY",
  "name": "Example Company UAB",
  "code": "123456789",
  "phone": "+37060000000",
  "email": "info@example.com",
  "address": "Example street 1, Vilnius",
  "person": "John Smith",
  "vat": "LT123456789",
  "website": "https://example.com",
  "city": "Vilnius",
  "meta": {
    "payment_terms": "14 days"
  }
}

Bulk Contacts Example

{
  "key": "YOUR_API_KEY",
  "contacts": [
    {
      "name": "First Company",
      "code": "100001",
      "email": "first@example.com"
    },
    {
      "name": "Second Company",
      "code": "100002",
      "phone": "+37060000002",
      "meta": {
        "city": "Kaunas"
      }
    }
  ]
}

Responses

Single-contact success:

{
  "status": "ok",
  "data": {
    "id": 123,
    "name": "Example Company UAB",
    "code": "123456789",
    "contact_meta": [
      { "field": "vat", "value": "LT123456789" }
    ]
  }
}

Bulk response statuses:

"status": "ok" when all contacts were created/updated
"status": "partial" when some contacts succeeded and some failed
"status": "error" when none of the contacts were created/updated

{
  "status": "partial",
  "data": {
    "created": [ /* Contact objects */ ],
    "errors": [
      { "index": 1, "error": "name invalid" }
    ],
    "count_created": 1,
    "count_errors": 1
  }
}

Error Responses

{ "status": "error", "data": "api disabled" }
{ "status": "error", "data": "no key" }
{ "status": "error", "data": "wrong key" }
{ "status": "error", "data": "name invalid" }
{ "status": "error", "data": "contacts must be array" }