# Datalyse API — full reference

Datalyse is a multi-tenant CRM and communication platform. Base URL for all endpoints: https://api.datalyse.io

## Authentication

Every endpoint requires an API access token passed in the `token` parameter (query string for GET, JSON body for other methods). Get your token by signing in at /devs/ (OAuth) — it is your personal API key and scopes every request to your company account.

Machine-readable alternative: OpenAPI 3.1 spec at /devs/openapi.json

## Calendarwidget

### calendarwidget_get_config

`GET https://api.datalyse.io/api/1.0/calendarwidget/getconfigurationbookingcalendar.json`

Get public calendar configuration. Returns availability ranges (per-day, minutes from midnight), duration, timezone and company logo. Calendar must have enabled=true. No authentication required (public endpoint).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| bookingId | string | yes | Calendar widget ObjectId (query param) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/calendarwidget/getconfigurationbookingcalendar.json?bookingId='
```

### calendarwidget_availability

`GET https://api.datalyse.io/api/1.0/calendarwidget/availabilityByDay.json`

Get available time slots for a specific date. Returns UTC ISO slots filtered by agent availability. How it works: 1) Load calendar config 2) Check enabled=true 3) Get availability ranges for the day of week 4) Generate slots every {duration} minutes within each range 5) Filter out past slots 6) For each slot check if at least ONE assigned agent has no conflicting task in calendar collection 7) Return available slots as UTC ISO strings. No authentication required (public endpoint).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| bookingId | string | yes | Calendar widget ObjectId (query param) |  |
| selectedDay | string | yes | Date in YYYY-MM-DD format (query param) | 2026-03-30 |
| timezone | string | no | IANA timezone string (optional query param, auto-detected from company country if not sent) | Europe/Madrid |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/calendarwidget/availabilityByDay.json?bookingId=&selectedDay=2026-03-30&timezone=Europe%2FMadrid'
```

### calendarwidget_create_booking

`POST https://api.datalyse.io/api/1.0/calendarwidget/booking.json`

Create an appointment booking. How it works: 1) Load calendar config, check enabled=true 2) Calculate UTC start/end from start_time + duration 3) Find assigned agents 4) Check which agents already have a task at that date+time 5) Pick first free agent 6) Detect existing lead by phone then by email 7) If no lead found create new lead (source: calendarwidget) 8) Create calendar task via appexpress_modal_addcalendar() 9) Return agent info. No authentication required (public endpoint).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| booking_id | string | yes | Calendar widget ObjectId |  |
| start_time | string | yes | ISO 8601 UTC datetime of the chosen slot (e.g. 2026-03-30T09:00:00.000Z) |  |
| timezone | string | no | IANA timezone string (optional, auto-detected from company country if not sent) | Europe/Madrid |
| contact | object | yes | Contact info object: { name: string, email: string, phone: string (with intl prefix), country: string (ISO 2-char code), notes: string } | [object Object] |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/calendarwidget/booking.json' \
  -H 'Content-Type: application/json' \
  -d '{"booking_id":"","start_time":"","timezone":"Europe/Madrid","contact":{"name":"John Doe","email":"john@example.com","phone":"+34600000000","country":"es","notes":""}}'
```

## Companies

### get_companies

`POST https://api.datalyse.io/api/1.0/companies/get.json`

Get a list of companies

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| var_status | string | no | Show only results with this status (optional) |  |
| var_agentfilter | string | no | Show only results for this agent ID (optional) |  |
| search_value | string | no | Text to search for (optional) |  |
| datefrom | string | no | Start date for filtering results (optional, format: YYYY-MM-DD) |  |
| dateto | string | no | End date for filtering results (optional, format: YYYY-MM-DD) |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companies/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### edit_company

`POST https://api.datalyse.io/api/1.0/companies/edit.json`

Edit a company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| company_lead_id | string | yes | ID of the company to edit |  |
| name | string | no | Company name (optional) |  |
| phone | string | no | Phone number with international prefix (optional) |  |
| email | string | no | Email (optional) |  |
| country | string | no | Country ISO code (optional) |  |
| status | string | no | Status ID (optional) |  |
| agent_id | string | no | Agent ID or "unassigned" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companies/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","company_lead_id":""}'
```

### delete_company

`POST https://api.datalyse.io/api/1.0/companies/delete.json`

Delete a company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| company_lead_id | string | yes | ID of the company to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companies/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","company_lead_id":""}'
```

### add_note_to_company

`POST https://api.datalyse.io/api/1.0/companies/addnote.json`

Add a note to a company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| company_lead_id | string | yes | ID of the company |  |
| text | string | yes | Text of the note | Hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companies/addnote.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","company_lead_id":"","text":"Hello world"}'
```

### get_company_activity

`POST https://api.datalyse.io/api/1.0/companies/getactivity.json`

Get activity/timeline for a company (includes activity from contacts inside the company)

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| company_lead_id | string | yes | ID of the company |  |
| type | string | no | Filter by activity type (optional) |  |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companies/getactivity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","company_lead_id":"","var_resultspage":"20","var_page":"1"}'
```

## Companyuserdata

### get_company_properties

`POST https://api.datalyse.io/api/1.0/companyuserdata/companyproperties.json`

Get all statuses, and additional data for company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/companyproperties.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### get_all_agents

`POST https://api.datalyse.io/api/1.0/companyuserdata/getallagents.json`

Get all agents for the company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/getallagents.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### get_price_per_credit

`POST https://api.datalyse.io/api/1.0/companyuserdata/getpricepercredit.json`

Get price per credit for VOIP calls and SMS, balance and plan info

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/getpricepercredit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### get_agents_types

`POST https://api.datalyse.io/api/1.0/companyuserdata/agentstypes.json`

Get all agent types (roles) for the company, including the number of agents assigned to each type

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/agentstypes.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### get_callerids

`POST https://api.datalyse.io/api/1.0/companyuserdata/callerids.json`

List ALL outbound caller IDs (phone lines) the company can dial from, filtered by agent permissions and campaign access. Returns a JSON object { status: 'ok', callerids: [...] } where 'callerids' is an array with one entry per available line — typically several entries, not just one. Each entry has a 'host' field which is the phone number in international format (digits only, no '+'), plus 'id', 'id_campana', 'pais' (ISO 3166-1 numeric country code: 724=ES, 826=GB, 840=US, 33=FR, 49=DE, 39=IT, 351=PT, 52=MX, 55=BR, 54=AR), 'alias', 'estado', and cost fields ('coste_mes', 'coste_xllam', 'coste_xmin'). Virtual rows (rotation) have 'virtual':1 and a synthetic 'host' like '9992078'. When the user asks 'dame mis callerids' / 'qué líneas tengo' / 'all my numbers', you MUST call this endpoint and show EVERY entry in the returned 'callerids' array — never truncate, never show only the first one. Use the 'host' value as the caller_id parameter when calling /api/1.0/sendvoicecall/createcall.json.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/callerids.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### invoices_get

`POST https://api.datalyse.io/api/1.0/companyuserdata/invoicesget.json`

Get invoices for the authenticated agent, optionally filtered by date range

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| date_start | string | no | Start timestamp for date range filter (optional) |  |
| date_end | string | no | End timestamp for date range filter (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/invoicesget.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### companyuserdata_myuserdata

`POST https://api.datalyse.io/api/1.0/companyuserdata/myuserdata.json`

Get the full authenticated agent/user record from the clients collection

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/companyuserdata/myuserdata.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

## Costexplorer

### costexplorer_get

`POST https://api.datalyse.io/api/1.0/costexplorer/get.json`

Get aggregated cost/usage data from the calls_leads collection grouped by configurable dimensions with a date range filter. By default returns only real communication records (answered/received calls, SMS, WhatsApp) grouped by agent_id and type — excludes AI, file, payment, credit and other internal service types unless explicitly overridden via service_type. Date range must be within a single calendar year. Only master/admin users can call this endpoint. Use this to answer questions like 'cost of calls per agent this month', 'total SMS cost by country', or 'which agent spent most credits on callouts'.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| datestart_unix | number | yes | Start date as UNIX timestamp in seconds UTC (inclusive). Example: 1767225600 corresponds to 2026-01-01 00:00 UTC. |  |
| dateend_unix | number | yes | End date as UNIX timestamp in seconds UTC (exclusive). Example: 1769904000 corresponds to 2026-02-01 00:00 UTC. |  |
| group_by | array | yes | Array of dimensions to group by. Allowed values: type, country, agent_id, month, day, hour, phone, destination. Default when omitted: ["agent_id","type"] — aggregates cost per agent and per service type. | ["agent_id","type"] |
| service_type | array | no | Filter by call types (optional). Default when omitted: ["callout","callin","callpush","callai","sms","smsin","whatsapp"] — aggregates received/answered calls (incl. AI voice), SMS and WhatsApp (excludes ai, aitts, payment, credit, file, etc). Allowed values in DB: callout, callin, callpush (AI push/vozpush call), callai (AI voice call), sms, smsin, whatsapp, ai, aitts, payment, credit, file, calendar, sale, ticket, emailin, emailout, emailreaded, form_completed, budget-status, fbleads, cli2cal, voiceline (monthly subscription fee of each phone line, one record per line and month). Note: callpush and callai are distinct AI voice service types, each grouped and labeled separately (not merged into 'ai'). | ["callout","callin","callpush","callai","sms","smsin","whatsapp"] |
| var_agents_id | array | no | Filter by agent IDs (optional, admin/master only). Admin users are limited to agents in their department. |  |
| collapse_by | array | no | Re-aggregate results by these dimensions after initial grouping (optional). Subset of group_by dimensions. |  |
| timezone | string | no | Timezone for date range validation (optional, example: Europe/Madrid). Used to ensure the date range stays within a single calendar year in the user's local timezone. Defaults to UTC if omitted or invalid. | Europe/Madrid |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/costexplorer/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","datestart_unix":"","dateend_unix":"","group_by":"[\"agent_id\",\"type\"]","service_type":"[\"callout\",\"callin\",\"callpush\",\"callai\",\"sms\",\"smsin\",\"whatsapp\"]","timezone":"Europe/Madrid"}'
```

### costexplorer_getlistcallsleads

`POST https://api.datalyse.io/api/1.0/costexplorer/getlistcallsleads.json`

Get call records grouped by agent and country with cost calculated from per-credit tariff. Dates in UNIX UTC seconds

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| datestart_unix | number | yes | Start date as UNIX timestamp UTC seconds (inclusive) |  |
| dateend_unix | number | yes | End date as UNIX timestamp UTC seconds (inclusive) |  |
| service_type | array | no | Filter by call types array e.g. ['callout','callin','sms'] (optional, returns all types if empty). callpush (AI push/vozpush call) and callai (AI voice call) are distinct service types. |  |
| var_agentfilterpayments | string | no | Filter by single agent ID (optional) |  |
| var_agents_id | array | no | Filter by multiple agent IDs (optional) |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/costexplorer/getlistcallsleads.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","datestart_unix":"","dateend_unix":""}'
```

### costexplorer_calls

`POST https://api.datalyse.io/api/1.0/costexplorer/calls.json`

Call report: returns a paginated list of individual communication records (inbound/outbound calls, SMS, WhatsApp) for a date range, plus aggregate stats (total calls, answered, unanswered, total duration in seconds, total credits). Reads from monthly calls_leads collections and applies agent RBAC automatically. By default filters only real communications (callout, callin, sms, smsin, whatsapp) and excludes AI, files, payments, credits and other non-communication service types — override with service_type to include them. Use this to answer questions like 'show me my calls last week', 'how many calls did agent X make in March', 'list missed calls today', 'how many WhatsApp messages did I receive', or 'what's my call cost this month'. All dates are UNIX timestamps in seconds.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| datestart_unix | number | yes | Start date as UNIX timestamp UTC seconds (inclusive). If omitted or invalid, defaults to current month. Example: 1767225600 corresponds to 2026-01-01 00:00 UTC. |  |
| dateend_unix | number | yes | End date as UNIX timestamp UTC seconds (inclusive). If omitted or invalid, defaults to current month. Example: 1769817599 corresponds to 2026-01-31 23:59 UTC. |  |
| service_type | array | no | Filter by call types (optional). Default when omitted: ["callout","callin","callpush","callai","sms","smsin","whatsapp"] — filters received/answered calls (incl. AI voice), SMS and WhatsApp. Allowed values in DB: callout, callin, callpush (AI push/vozpush call), callai (AI voice call), sms, smsin, whatsapp, ai, aitts, payment, credit, file, calendar, sale, ticket, emailin, emailout, emailreaded, form_completed, budget-status, fbleads, cli2cal, voiceline (monthly subscription fee of each phone line, one record per line and month). Note: callpush and callai are distinct AI voice service types, each grouped and labeled separately (not merged into 'ai'). Example: ["callout","callin"] | ["callout","callin","callpush","callai","sms","smsin","whatsapp"] |
| status | string | no | Filter by call status (optional). Common values: ANSWER (answered), NO ANSWER, BUSY, FAILED, CANCEL |  |
| phone | string | no | Filter by phone number substring (optional, case insensitive) |  |
| var_agents_id | array | no | Filter by agent IDs (optional). Ignored for agent-type users (they only see their own calls). Admin users are limited to agents in their department. |  |
| page | number | no | Page number, starts at 1 (optional, default 1) | 1 |
| pageSize | number | no | Records per page, between 10 and 500 (optional, default 50) | 50 |
| timezone | string | no | Timezone for date filtering context (optional, example: Europe/Madrid). | Europe/Madrid |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/costexplorer/calls.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","datestart_unix":"","dateend_unix":"","service_type":"[\"callout\",\"callin\",\"callpush\",\"callai\",\"sms\",\"smsin\",\"whatsapp\"]","page":1,"pageSize":50,"timezone":"Europe/Madrid"}'
```

## Domains

### domain_check_availability

`GET https://api.datalyse.io/api/1.0/domains/check.json`

Check domain availability and pricing. Returns availability status, price in credits, original price, current balance and whether the user can afford it.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to check (e.g. example.com) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/domains/check.json?token=YOUR_APIKEY&domain='
```

### domain_register

`POST https://api.datalyse.io/api/1.0/domains/register.json`

Register (buy) a new domain. Requires registrant contact info. Saves domain with status pending_verification, deducts credits from balance. Domain must be activated after email verification.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to register |  |
| years | integer | yes | Number of years to register (default: 1) | 1 |
| contact.firstName | string | yes | Registrant first name |  |
| contact.lastName | string | yes | Registrant last name |  |
| contact.address1 | string | yes | Registrant address |  |
| contact.city | string | yes | Registrant city |  |
| contact.state | string | yes | Registrant state/province |  |
| contact.postalCode | string | yes | Registrant postal code |  |
| contact.country | string | yes | Registrant country code (e.g. ES, US) |  |
| contact.phone | string | yes | Registrant phone (e.g. +34.612345678) |  |
| contact.email | string | yes | Registrant email |  |
| contact.org | string | no | Registrant organization (optional) |  |
| dnsRecords | array | no | DNS records to configure (optional, uses defaults if not provided) |  |
| nameservers | array | no | Custom nameservers (optional) |  |
| mail | boolean | no | Enable mail configuration (optional) |  |
| defaultDns | boolean | no | Use default DNS records (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/register.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":"","years":"1","contact.firstName":"","contact.lastName":"","contact.address1":"","contact.city":"","contact.state":"","contact.postalCode":"","contact.country":"","contact.phone":"","contact.email":""}'
```

### domain_activate

`POST https://api.datalyse.io/api/1.0/domains/activate.json`

Activate a pending domain after verification. Configures DNS records, registers domain in the mail server, creates reverse proxy routes for HTTPS (domain + www), sets default services (mail, web) and marks status as active.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to activate |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/activate.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":""}'
```

### domain_dns_add_service

`POST https://api.datalyse.io/api/1.0/domains/dns/add.json`

Add or update a DNS record for a specific service (e.g. mail, web, web). Fetches existing records, adds/replaces the new one, and creates a reverse proxy route with automatic HTTPS if the service requires it.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name |  |
| type | string | yes | DNS record type (default: A) | A |
| name | string | yes | DNS record name (default: @) | @ |
| content | string | yes | DNS record content (IP address or hostname) |  |
| ttl | integer | yes | TTL in seconds (default: 1800) | 1800 |
| server | string | yes | Service key for tracking (e.g. mail, crm, web). Used to create reverse proxy route and save service status. |  |
| priority | integer | no | Priority for MX records (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/dns/add.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":"","type":"A","name":"@","content":"","ttl":"1800","server":""}'
```

### domain_get_services

`GET https://api.datalyse.io/api/1.0/domains/servers.json`

Get the status of all configured services for a domain. Returns each service key, status, host and value.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to query |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/domains/servers.json?token=YOUR_APIKEY&domain='
```

### domain_get_managed

`GET https://api.datalyse.io/api/1.0/domains/managed.json`

Get all domains managed by the user's company. Returns domains filtered by company_id with status, verification state, SMTP/IMAP config and services. Does not include shared platform domains.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/domains/managed.json?token=YOUR_APIKEY'
```

### domain_add_custom

`POST https://api.datalyse.io/api/1.0/domains/add.json`

Add a custom (already owned) domain for verification. Saves it with status pending_verification and returns the required DNS records. The user must configure DNS and call dns/verify.json before activation.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to add |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/add.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":""}'
```

### domain_dns_verify

`GET https://api.datalyse.io/api/1.0/domains/dns/verify.json`

Verify DNS configuration for a domain. Performs real DNS lookups checking MX, SPF and DMARC records. If all pass, registers the domain in the mail server and marks it as active and verified.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to verify |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/domains/dns/verify.json?token=YOUR_APIKEY&domain='
```

### domain_delete

`POST https://api.datalyse.io/api/1.0/domains/delete_domain.json`

Delete a domain completely. Removes all email accounts associated with that domain from the mail server, disconnects all agents using emails on that domain, removes all reverse proxy routes (domain, www, service subdomains), and deletes the domain record from the database. System domains cannot be deleted.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/delete_domain.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":""}'
```

### domain_renew

`POST https://api.datalyse.io/api/1.0/domains/renewdomain.json`

Renew a registered domain. Verifies the domain belongs to the company, gets renewal pricing, checks credit balance, renews via the registrar, deducts credits and updates the expiry date in the database. External domains cannot be renewed from this platform. System domains cannot be renewed.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to renew |  |
| years | number | yes | Number of years to renew (default: 1) | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/renewdomain.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":"","years":1}'
```

### domain_mark_delete

`POST https://api.datalyse.io/api/1.0/domains/markasdelete.json`

Mark a domain for deletion. Changes the domain status to 'pending_delete' so it will not be automatically renewed when it expires. The domain is not deleted immediately — it remains active until expiration. System domains cannot be marked.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name to mark for deletion |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/markasdelete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":""}'
```

### domain_activate_services

`POST https://api.datalyse.io/api/1.0/domains/activate_services.json`

Activate multiple services for a domain in a single API call. Accepts an array of service keys. For registered domains, creates all DNS records in a single batch call to the registrar. For external domains, verifies DNS is correctly configured before activating. Creates reverse proxy routes for each service that needs HTTPS.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| domain | string | yes | Domain name |  |
| services | array | yes | Array of service keys to activate: mail, web, crm, meets, infinitycloud, cabinet, webtrade | crm,meets,mail |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/domains/activate_services.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","domain":"","services":["crm","meets","mail"]}'
```

## Emails

### email_unsubscribe

`GET https://api.datalyse.io/api/1.0/emails/unsubscribe.json`

Unsubscribe an email address

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| email | string | yes | Email address to unsubscribe |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/emails/unsubscribe.json?email='
```

### email_send

`POST https://api.datalyse.io/api/1.0/emails/send.json`

Send an email

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| to | string | yes | Recipient email address |  |
| subject | string | yes | Email subject | Hello |
| html | string | yes | Email body in HTML | <p>Hello world</p> |
| cc | string | no | CC recipients (optional) |  |
| bcc | string | no | BCC recipients (optional) |  |
| lead_id | string | no | Associate email with a contact ID (optional) |  |
| opportunity_id | string | no | Associate email with an opportunity ID (optional) |  |
| signature_id | string | no | Append this signature to the email (optional, get from signatures/get) |  |
| tracking | string | no | Enable open tracking, set to "y" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/send.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","to":"","subject":"Hello","html":"<p>Hello world</p>"}'
```

### email_get_inbox

`POST https://api.datalyse.io/api/1.0/emails/get.json`

Get emails from inbox or sent folder

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| type | string | yes | Folder: "inbox" (default) or "sent" | inbox |
| var_resultspage | string | yes | Maximum number of results | 20 |
| var_page | string | yes | Page number | 1 |
| search_value | string | no | Search in subject (optional) |  |
| unread_only | string | no | Show only unread, set to "y" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","type":"inbox","var_resultspage":"20","var_page":"1"}'
```

### email_get_one

`POST https://api.datalyse.io/api/1.0/emails/getone.json`

Get a single email with full body

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| email_id | string | yes | ID of the email |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/getone.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","email_id":""}'
```

### email_get_signatures

`POST https://api.datalyse.io/api/1.0/emails/signatures/get.json`

Get all email signatures

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### email_save_signature

`POST https://api.datalyse.io/api/1.0/emails/signatures/save.json`

Create or update an email signature

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| signature_id | string | yes | ID of signature to update (omit to create new) |  |
| name | string | yes | Signature name | My Signature |
| html | string | yes | Signature HTML content | <p>Best regards</p> |
| is_default | string | yes | Set as default signature, "true" or "false" | false |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/save.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","signature_id":"","name":"My Signature","html":"<p>Best regards</p>","is_default":"false"}'
```

### email_delete_signature

`POST https://api.datalyse.io/api/1.0/emails/signatures/delete.json`

Delete an email signature

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| signature_id | string | yes | ID of the signature to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/signatures/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","signature_id":""}'
```

### email_get_templates

`POST https://api.datalyse.io/api/1.0/emails/templates/get.json`

Get all email templates

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### email_create_template

`POST https://api.datalyse.io/api/1.0/emails/templates/create.json`

Create a new email template

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| name | string | yes | Template name | My Template |
| subject | string | no | Default email subject (optional) |  |
| html | string | yes | Template HTML content | <p>Hello {{name}}</p> |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/create.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","name":"My Template","html":"<p>Hello {{name}}</p>"}'
```

### email_edit_template

`POST https://api.datalyse.io/api/1.0/emails/templates/edit.json`

Edit an email template

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| template_id | string | yes | ID of the template to edit |  |
| name | string | no | Template name (optional) |  |
| subject | string | no | Default email subject (optional) |  |
| html | string | no | Template HTML content (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","template_id":""}'
```

### email_delete_template

`POST https://api.datalyse.io/api/1.0/emails/templates/delete.json`

Delete an email template

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| template_id | string | yes | ID of the template to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/emails/templates/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","template_id":""}'
```

## Entities

### entities_get_schemas

`POST https://api.datalyse.io/api/1.0/entities/schemas.json`

Get ALL CRM entities of the company with their full schemas in a single call: property identifiers, types, required/unique flags, select options, statuses, associations and the exact endpoints to create, query and edit records of each entity. This is the entry point for AI assistants, MCP integrations and developers: call it first and you will not need to fetch company properties or configuration from any other endpoint. ENTITY TYPES: entities with system='y' are the 6 built-in CRM entities (leads = Contacts, companies, opportunities = Deals, tasks, tickets, budgets); entities with system=null are CUSTOM entities created by this company and their key always starts with 'cust_'. Both share exactly the same schema shape. STATUSES: an entity can have status groups (statusgroups). Every status has a stable 'id', a human 'label', a color and (built-in entities only) a numeric 'legacyIndex'. The 'mode' of the group tells you which value is stored in records and therefore what to send in filters and on creation: mode 'index' (contacts/companies) uses the legacyIndex, mode 'id' (custom entities) uses the status 'id'. The property that backs each group carries 'statusgroup' and 'statusoptions'. ASSOCIATIONS: a property of type 'association' links a record to another entity: 'targetEntity' says which entity it points to and the stored value is the _id string of the target record; the entity's 'associations' array lists all its links. Association properties are CREATED through /api/1.0/entities/saveproperty.json (type 'association' + targetEntity) or directly at entity creation with the 'properties' parameter of /api/1.0/entities/createentity.json. GET is also supported with the same parameters as query string.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/schemas.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

Get all entities and schemas:

```json
{
  "token": "YOUR_APIKEY"
}
```

Notes:

- Property identifiers are the keys of the 'properties' object of each entity. Use them as field names in the 'values' object of createrecord.json, as filter keys in getrecords.json and in the create/edit endpoints of built-in entities. Custom-entity identifiers are auto-generated random strings: never guess them, always read them here.
- SYSTEM vs CUSTOM: system='y' marks the 6 built-in entities (leads, companies, opportunities, tasks, tickets, budgets); custom entities have system=null and a key starting with 'cust_'. Custom entities are created with /api/1.0/entities/createentity.json (ONE call creates the entity with all its initial properties, associations and statuses).
- New records with no status get the status flagged 'isdefault':'y'. The default is ALWAYS the first status: on built-in entities with mode 'index' it is the fixed legacyIndex 0 (cannot be deleted or reordered); on custom entities it is the first live status in display order — reordering statuses moves the default to the new first one.
- ASSOCIATIONS: to link a record when creating/editing it, pass the _id string of the target record as the value of the association property (find ids with getrecords.json). getrecords.json returns human-readable labels of linked records in 'assoclabels'. To CREATE a new association between two entities, call /api/1.0/entities/saveproperty.json with type 'association' (targetEntity = the entity to link to) — or include it in the 'properties' of createentity.json when creating the entity.
- Every entity carries endpoint hints — follow them instead of hardcoding routes: 'create' (create records; null for tasks and budgets), 'records' (query records), 'edit' (edit ONE existing record: /api/1.0/entities/editrecord.json for custom entities, the module endpoint like /api/1.0/leads/edit.json for built-in ones) and, on custom entities only: 'entity_edit' (rename / icon / color via editentity.json), 'property_save' (create/edit properties and associations via saveproperty.json) and 'status_save' (add/edit statuses via savestatus.json).
- DATES: every date in the API is a unix UTC epoch in SECONDS (never milliseconds, never date strings in storage). Properties of type 'datetime' (and legacy 'date'), the built-in datestartunixutc/dateendunixutc of tasks, opportunities 'expecteddate' and the system fields creation_date/last_update all follow this contract: send epoch seconds when writing (date strings like 'yyyy-mm-dd hh:mm' are converted server-side), receive epoch seconds when reading, and filter by range in getrecords.json with {"identifier": {"gte": ..., "lte": ...}}. The CRM renders them in each user's timezone.

### entities_get_records

`POST https://api.datalyse.io/api/1.0/entities/getrecords.json`

Query records of any CRM entity — contacts (entitykey 'leads'), 'companies', 'opportunities', 'tasks', 'tickets' or any CUSTOM entity ('cust_...') — with filters on schema properties, free-text search, ordering, pagination and creation-date range. Records are returned CLEAN: only 'id', base fields (agent_id, agents_id, creation_date, last_update and, on entities that store it — opportunities/tasks —, a raw 'date' field), the properties defined in the entity schema, resolved status labels (extra '<statusfield>_label' fields) and display labels of linked records ('assoclabels', custom entities). Property identifiers for filters come from /api/1.0/entities/schemas.json. Results respect the visibility of the user linked to the token: masters see everything; agents see their own records; admins see their department on built-in entities and EVERYTHING on custom entities (no department scoping there). For budgets use /api/1.0/budgets/getlist.json.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| entitykey | string | yes | Entity key from schemas.json: 'leads' (contacts), 'companies', 'opportunities', 'tasks', 'tickets', or a custom key starting with 'cust_'. Required. | leads |
| filters | object | no | Filters on property identifiers (from schemas.json). Simple form {"identifier": "value"} means equals; an array value means IN; advanced form {"identifier": {"op": "gte", "value": 100}} with ops: eq, ne, in, nin, gt, gte, lt, lte, re (regex contains, case-sensitive; only meaningful on text-like properties — on 'number' properties it never matches anything, and on opportunities 'expecteddate' it is rejected with invalid_filter_op_re_for_expecteddate). Status fields: send the legacyIndex for contacts/companies (statusgroups mode 'index') or the status 'id' for custom entities (mode 'id'). Association properties: send the _id string of the target record. agent_id and agents_id support only eq/in (agents_id is an array: eq = contains, in = contains any). Also accepts a JSON-encoded string. (optional) RANGE/multi-op form: a value object WITHOUT 'op' whose keys are operators applies them all to the identifier — {"identifier": {"gte": 100, "lte": 200}} (both bounds merged with AND); works for any property type and is THE way to express from-to ranges in a single call. | [object Object] |
| search | string | no | Free-text search over the entity's text properties (name, email, phone...). Case-insensitive. (optional) |  |
| page | string | no | Page number, starts at 1. (optional) | 1 |
| perpage | string | no | Results per page, max 100. (optional) | 20 |
| orderby | string | no | Property identifier to sort by. Defaults to creation date, newest first. (optional) | creation_date |
| orderdir | string | no | Sort direction: 'asc' or 'desc'. Defaults to 'desc'. (optional) | desc |
| count | string | no | Set to 'y' to also get the exact total count in 'total' (slower). By default 'total' is null and pagination relies on 'hasmore'. (optional) |  |
| datefrom | string | no | Start of creation-date range, format YYYY-MM-DD. Requires dateto and timezone. (optional) | 2026-01-01 |
| dateto | string | no | End of creation-date range, format YYYY-MM-DD. Requires datefrom and timezone. (optional) | 2026-12-31 |
| timezone | string | no | IANA timezone for the date range, e.g. Europe/Madrid. Required together with datefrom and dateto. (optional) | Europe/Madrid |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/getrecords.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"leads","filters":{"status":"0","country":"es"},"page":"1","perpage":"20","orderby":"creation_date","orderdir":"desc","datefrom":"2026-01-01","dateto":"2026-12-31","timezone":"Europe/Madrid"}'
```

Contacts with status New (legacyIndex 0):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "leads",
  "filters": {
    "status": "0"
  },
  "perpage": 20
}
```

Spanish contacts created in 2026, newest first:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "leads",
  "filters": {
    "country": "es"
  },
  "datefrom": "2026-01-01",
  "dateto": "2026-12-31",
  "timezone": "Europe/Madrid",
  "orderby": "creation_date",
  "orderdir": "desc"
}
```

Custom entity: price >= 100000 AND status Available (by id), with exact total:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "filters": {
    "ab12price8k2j3h4g5": {
      "op": "gte",
      "value": 100000
    },
    "status_main": "st_1a2b3c"
  },
  "count": "y"
}
```

Free-text search in companies:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "companies",
  "search": "acme"
}
```

Records linked to a contact (association property = contact _id):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "filters": {
    "ab12owner9q8w7e6r5": "69d9d868740030527e46055a"
  }
}
```

Tasks between two dates (range on a datetime field):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "tasks",
  "filters": {
    "datestartunixutc": {
      "gte": "2026-01-01",
      "lte": "2026-02-01 23:59"
    }
  },
  "orderby": "datestartunixutc",
  "orderdir": "asc"
}
```

Notes:

- Records come CLEAN: only fields defined in the entity schema plus id/agent_id/agents_id/creation_date/last_update (and a raw 'date' field on entities that store it, e.g. opportunities — epoch backing field of expecteddate — and tasks). Status fields are also resolved to human labels in extra '<statusfield>_label' fields (e.g. status '0' + status_label 'New'). For custom entities, 'assoclabels' maps each association property to the display label of the linked record.
- Pagination: by default 'total' is null and 'hasmore' tells you if there is a next page (cheap). Send count='y' only when you really need the exact total.
- creation_date and last_update are unix UTC epoch SECONDS (never milliseconds) — like EVERY date field of the API. Status filter values: legacyIndex for contacts/companies, status 'id' for custom entities (check statusgroups[].mode in schemas.json).
- Visibility is enforced server-side with the permissions of the user linked to the token: agents only see their records; admins see their department on built-in entities and everything on custom entities. Filtering by agent_id supports only eq/in.
- Call /api/1.0/entities/schemas.json first to discover entity keys and property identifiers.
- Each record's 'id' is the record_id you need to EDIT that record afterwards: /api/1.0/entities/editrecord.json for custom entities, or the module edit endpoint (e.g. /api/1.0/leads/edit.json) for built-in entities — see the 'edit' hint of each entity in schemas.json.
- Opportunities: 'expecteddate' (expected close date) works both in 'filters' and 'orderby'. As filter value send epoch UTC SECONDS (a millisecond epoch is auto-normalized) or a 'yyyy-mm-dd' date string (parsed like the write endpoints, at 00:00); anything else returns invalid_filter_value_expecteddate instead of matching nothing. For op 'in'/'nin' send an array (or a comma-separated string). Op 're' is not supported on this field. Internally it maps to the physical 'date' field. Example filter: {"expecteddate": {"op": "lte", "value": 1790000000}}.
- DATE RANGES: 'datetime' (and legacy 'date') properties store unix UTC epoch seconds — on CUSTOM entities and on BUILT-IN ones alike (e.g. tasks 'datestartunixutc' / 'dateendunixutc'). Filter from-date-to-date with the RANGE form (several ops in one value object): filters = {"datestartunixutc": {"gte": 1790000000, "lte": 1795000000}}. Values accept epoch seconds (ms auto-normalized) or 'yyyy-mm-dd' / 'yyyy-mm-dd hh:mm' strings (converted server-side), so {"gte": "2026-01-01", "lte": "2026-02-01"} also works. Op 're' is rejected on date fields.
- AGENT FILTERS: 'agent_id' is the MAIN assigned employee (single id; also accepts 'unassigned') and 'agents_id' is the ARRAY of ALL assigned employees. On 'agents_id', op 'eq' matches records whose array CONTAINS that agent and op 'in' matches records containing ANY of the listed agents — e.g. filters = {"agents_id": {"op": "in", "value": ["64a1...", "64b2..."]}}. Both fields allow ONLY eq/in; users of type 'agent' cannot filter by agent fields, and admins only within the agents they manage. Works identically on custom and built-in entities.
- SYSTEM DATES: every entity exposes 'datesales' (creation date) and 'last_updatesales' (last update) — virtual identifiers over the physical creation_date/last_update fields, BOTH stored as unix UTC epoch in SECONDS. Filter them by range like any date: filters = {"last_updatesales": {"gte": "2026-07-01", "lte": "2026-07-21 23:59"}} (epoch seconds also accepted). Ops eq/ne/gt/gte/lt/lte; 're' is rejected. Works on custom and built-in entities.

### entities_create_record

`POST https://api.datalyse.io/api/1.0/entities/createrecord.json`

Create a record in a CRM entity using its schema: contacts (entitykey 'leads'), companies (entitykey 'companies') or any CUSTOM entity (entitykey 'cust_...'). Field names inside 'values' are the property identifiers returned by /api/1.0/entities/schemas.json. STATUSES: for contacts/companies send the status legacyIndex in the 'status' parameter; for custom entities send the status 'id' inside values using the status group's docField (e.g. values.status_main = 'st_1a2b3c'); if omitted, the status flagged 'isdefault':'y' in schemas.json is applied (or, if none is flagged, the first live status in display order — the first one schemas.json lists). ASSOCIATIONS (custom entities): to link the new record to another record, pass the _id string of the target record as the value of the association property. For opportunities and tickets use their specific create endpoints (the 'create' hint of the schemas response tells you which endpoint to use for each entity).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| entitykey | string | yes | Entity key from schemas.json: 'leads' (contacts), 'companies', or a custom key starting with 'cust_'. Required. | leads |
| values | object | yes | Object mapping property identifiers (from schemas.json) to values. Required properties of the entity must be present. Association properties take the _id string of the target record. Also accepts a JSON-encoded string. Required. | [object Object] |
| agent_id | string | no | Only for 'leads'/'companies': agent _id to assign the record to, or 'unassigned' to assign it to all agents (default). For custom entities the record is always created by the client linked to the token. (optional) | unassigned |
| status | string | no | Only for 'leads'/'companies': status legacyIndex (see statusoptions in schemas.json). Defaults to 0. For custom entities pass the status 'id' inside values using the statusgroup docField (e.g. values.status_main). (optional) | 0 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/createrecord.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"leads","values":{"name":"Marc","email":"example@exampleemail.com","phone":"34682288888"},"agent_id":"unassigned","status":"0"}'
```

Create a contact:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "leads",
  "values": {
    "name": "Marc",
    "lastname": "Doe",
    "email": "example@exampleemail.com",
    "phone": "34682288888",
    "country": "es"
  },
  "agent_id": "unassigned",
  "status": "0"
}
```

Create a company:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "companies",
  "values": {
    "name": "Acme S.L.",
    "email": "info@acme.com"
  }
}
```

Create a custom record with status by id:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "values": {
    "ab12name7f3k2m9q1z": "Villa Sunrise",
    "ab12price8k2j3h4g5": 250000,
    "status_main": "st_1a2b3c"
  }
}
```

Create a custom record LINKED to a contact (association property = contact _id):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "values": {
    "ab12name7f3k2m9q1z": "Villa Sunrise",
    "ab12owner9q8w7e6r5": "69d9d868740030527e46055a"
  }
}
```

Notes:

- Call /api/1.0/entities/schemas.json first to discover entity keys and property identifiers; never guess identifiers. Exception: if you JUST created the entity with createentity.json, its response 'created.properties' already maps every property name to its identifier — use those directly, no schemas.json call needed.
- For 'leads'/'companies' this endpoint runs exactly the same pipeline as /api/1.0/leads/create.json: validation and casting of company properties, duplicate detection by unique properties, workflows and notifications included. If a duplicate is detected the error response includes 'existing_record_id'.
- For custom entities values are validated against the schema: required and unique properties are enforced, status values must be live status ids, values of type 'select' must be one of the property's options (their 'text'; the 'invalid option for property <identifier>' error message lists the valid ones), and association targets must exist in their entity or the request is rejected.
- The default status is always the FIRST one of the group (schemas.json lists them in that order and flags it 'isdefault':'y'); on custom entities, reordering statuses in the CRM moves the default to the new first status.
- Association values are always the _id string of the target record; find ids with /api/1.0/entities/getrecords.json.
- The creator of the record is always the client linked to the token.
- To UPDATE an existing record afterwards use /api/1.0/entities/editrecord.json (custom entities) or the module edit endpoint of built-in entities; the record_id returned here is the id to use.
- Values of 'datetime' (and legacy 'date') properties: send unix UTC epoch in SECONDS (preferred; milliseconds are auto-normalized) or 'yyyy-mm-dd' / 'yyyy-mm-dd hh:mm'. The value is ALWAYS stored as unix UTC epoch in seconds (never as a date string) and the CRM shows it converted to each user's timezone. An unparseable value rejects the whole request with 'invalid date for property <identifier>'. Empty string clears the field.
- PROPERTY TYPES & VALUE FORMATS (what to send as the value of each property in createrecord/editrecord 'values'): text/textarea/phone/email -> string; number -> number (or numeric string); select -> the 'text' of one of the property's options (exact match; '' clears); tags -> array of strings (["vip","madrid"]); country -> lowercase ISO-2 code ('es', 'fr'); datetime (and legacy date) -> unix UTC epoch in SECONDS (preferred; ms auto-normalized; 'yyyy-mm-dd' and 'yyyy-mm-dd hh:mm' also accepted) — ALWAYS stored as epoch, shown in each user's timezone; association -> the _id string (24 hex chars) of the target record (find it with getrecords.json); status of the entity -> the status 'id' ('st_...') in the group's docField (usually values.status_main).

### entities_edit_record

`POST https://api.datalyse.io/api/1.0/entities/editrecord.json`

Edit (update) an EXISTING record of a CUSTOM entity ('cust_...') by its record id. PARTIAL update: only the property identifiers present in 'values' are modified; every other field keeps its value. Field names inside 'values' are the property identifiers returned by /api/1.0/entities/schemas.json — never guess them. STATUSES: send the status 'id' using the status group's docField as field name (e.g. values.status_main = 'st_4d5e6f'). ASSOCIATIONS: to link (or re-link) the record to another record, pass the _id string of the target record as the value of the association property. All changes are validated against the entity schema (required, unique, valid status ids, association target must exist) and the change is logged in the record's activity feed. Built-in entities (leads, companies, opportunities, tasks, tickets, budgets) are edited through their own endpoints (/api/1.0/<entity>/edit.json); calling this one with a built-in entitykey returns 'use_specific_endpoint' telling you which endpoint to use.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| entitykey | string | yes | Key of the CUSTOM entity (starts with 'cust_'), from schemas.json. Built-in entities must use their own edit endpoint. Required. | cust_ab12cd34ef56gh78 |
| record_id | string | yes | The _id of the record to edit: the 'id' field returned by getrecords.json or the 'record_id' returned by createrecord.json (24-char hex). Required. | 69d9d868740030527e46055a |
| values | object | yes | Object mapping property identifiers (from schemas.json) to their NEW values. PARTIAL: only identifiers present here are updated. Status fields use the group's docField with the status 'id' as value; association properties take the _id string of the target record; unknown keys are ignored. Also accepts a JSON-encoded string. Required. | [object Object] |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/editrecord.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"cust_ab12cd34ef56gh78","record_id":"69d9d868740030527e46055a","values":{"ab12price8k2j3h4g5":199000}}'
```

Change one field of a record:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "record_id": "69d9d868740030527e46055a",
  "values": {
    "ab12price8k2j3h4g5": 199000
  }
}
```

Change the record's status (status id from schemas.json):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "record_id": "69d9d868740030527e46055a",
  "values": {
    "status_main": "st_4d5e6f"
  }
}
```

Link the record to a contact (association property = contact _id):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "record_id": "69d9d868740030527e46055a",
  "values": {
    "ab12owner9q8w7e6r5": "69d9d868740030527e46055a"
  }
}
```

Update several fields at once:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "record_id": "69d9d868740030527e46055a",
  "values": {
    "ab12name7f3k2m9q1z": "Villa Sunrise II",
    "ab12price8k2j3h4g5": 215000,
    "status_main": "st_1a2b3c"
  }
}
```

Notes:

- PARTIAL update: properties not present in values are left untouched. Clearing values: an empty string clears text-like properties (text, textarea, phone, email) and also 'select' and 'date' properties; for type number an empty string is stored as 0 and for type country it resets to 'wo' — do not send '' to clear those two types. Required properties cannot be emptied.
- Get the record id from getrecords.json (field 'id') or from createrecord.json (field 'record_id'). Get property identifiers and status ids from schemas.json — never guess them.
- Visibility is enforced with the permissions of the user linked to the token: agents can only edit their own records; editing a record you cannot see returns 'record_not_found'.
- Every effective change is logged automatically in the record's history/activity feed.
- Built-in entities: follow the 'edit' hint of each entity in schemas.json (e.g. /api/1.0/leads/edit.json for contacts). This endpoint is only for custom entities.
- Values of 'datetime' (and legacy 'date') properties: send unix UTC epoch in SECONDS (preferred; milliseconds are auto-normalized) or 'yyyy-mm-dd' / 'yyyy-mm-dd hh:mm'. The value is ALWAYS stored as unix UTC epoch in seconds (never as a date string) and the CRM shows it converted to each user's timezone. An unparseable value rejects the whole request with 'invalid date for property <identifier>'. Empty string clears the field.

### entities_create_entity

`POST https://api.datalyse.io/api/1.0/entities/createentity.json`

Create a NEW CUSTOM ENTITY in the CRM — a brand-new record type / custom object / custom module (e.g. 'Properties', 'Contracts', 'Invoices', 'Vehicles') — COMPLETE IN ONE SINGLE CALL: the entity itself (name, name_plural, icon, color) PLUS all its initial PROPERTIES (fields, associations included — 'properties' parameter) PLUS its initial STATUSES ('statuses' parameter — the first one becomes the default). THIS ENDPOINT IS THE TOOL FOR THAT and the RECOMMENDED way for AI assistants and integrations: if a user asks to create a custom entity ('entidad personalizada'), send EVERYTHING here in one request instead of chaining saveproperty/savestatus calls. Every property type is supported with the same format as saveproperty.json: text, tags, textarea, select (REQUIRES 'options'), phone, email, number, datetime (ALWAYS stored as unix UTC epoch in SECONDS), country, association (REQUIRES 'targetEntity' = an EXISTING entitykey). The entity is also born with a required 'Name' text property. The response's 'created' object maps every property name to its generated identifier (the auto-created 'Name' property included, flagged required:'y') and every status label to its id, so createrecord.json can be called IMMEDIATELY with no schemas.json lookup — just send a value for every required:'y' property. saveproperty.json and savestatus.json remain available to add MORE fields/statuses LATER or to edit existing ones. Built-in system entities (leads, companies, opportunities, tasks, tickets, budgets) already exist and cannot be created here. The token's user must be master or admin.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. The linked user must be master or admin. Required. | YOUR_APIKEY |
| name | string | yes | Singular name of the new entity. Required. | Property |
| name_plural | string | no | Plural name. Defaults to the singular name. (optional) | Properties |
| icon | string | no | Tabler icon class. Defaults to 'ti ti-box'. (optional) | ti ti-home |
| color | string | no | Hex color for the entity. Defaults to '#2563eb'. (optional) | #16a34a |
| properties | array | no | INITIAL properties (fields) of the entity, created in the SAME call: array of {name (required), type (defaults to 'text'; one of text, tags, textarea, select, phone, email, number, datetime, country, association), required ('y'/'n', default 'n'), unique ('y'/'n', default 'n'), options (REQUIRED for type select: array of strings or {text, textshow, selected:'y'\|'n'} objects), targetEntity (REQUIRED for type association: an EXISTING entitykey of the company — it cannot point to the entity being created), cardinality (association only, defaults to 'many-to-one')}. Max 100. Do NOT include a property named 'Name': the entity is always born with it. Every entry is validated upfront: if any is invalid NOTHING is created. More fields can be added later with /api/1.0/entities/saveproperty.json. Also accepts a JSON-encoded string. (optional) | [object Object],[object Object],[object Object],[object Object] |
| statuses | array | no | INITIAL statuses of the entity: array where each item is a label string or a {label, color} object. The FIRST one becomes the default status for new records. Max 100. Statuses can be added/edited later with /api/1.0/entities/savestatus.json. Also accepts a JSON-encoded string. (optional) | Available,[object Object],[object Object] |
| statusgroup | object | no | Alternative form of 'statuses' with a custom group name: {name, statuses:[...]} (same statuses format, e.g. {"name":"Pipeline","statuses":[{"label":"Draft"},{"label":"Confirmed","color":"#22c55e"}]}). Use one or the other, not both — if both are sent, 'statusgroup' wins and 'statuses' is ignored. (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/createentity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","name":"Property","name_plural":"Properties","icon":"ti ti-home","color":"#16a34a","properties":[{"name":"Price","type":"number"},{"name":"Type","type":"select","options":["Flat","House","Office"]},{"name":"Signing date","type":"datetime"},{"name":"Owner","type":"association","targetEntity":"leads"}],"statuses":["Available",{"label":"Reserved","color":"#f59e0b"},{"label":"Sold","color":"#ef4444"}]}'
```

Complete entity in ONE call (recommended): properties + association + statuses:

```json
{
  "token": "YOUR_APIKEY",
  "name": "Property",
  "name_plural": "Properties",
  "icon": "ti ti-home",
  "color": "#16a34a",
  "properties": [
    {
      "name": "Reference",
      "type": "text",
      "required": "y",
      "unique": "y"
    },
    {
      "name": "Price",
      "type": "number"
    },
    {
      "name": "Type",
      "type": "select",
      "options": [
        "Flat",
        "House",
        "Office"
      ]
    },
    {
      "name": "Signing date",
      "type": "datetime"
    },
    {
      "name": "Owner",
      "type": "association",
      "targetEntity": "leads"
    }
  ],
  "statuses": [
    "Available",
    {
      "label": "Reserved",
      "color": "#f59e0b"
    },
    {
      "label": "Sold",
      "color": "#ef4444"
    }
  ]
}
```

Minimal entity:

```json
{
  "token": "YOUR_APIKEY",
  "name": "Contract"
}
```

Entity with initial statuses only (fields can be added later):

```json
{
  "token": "YOUR_APIKEY",
  "name": "Excursion",
  "statuses": [
    "Draft",
    {
      "label": "Confirmed",
      "color": "#22c55e"
    }
  ]
}
```

Entity with a named status group:

```json
{
  "token": "YOUR_APIKEY",
  "name": "Excursion",
  "statusgroup": {
    "name": "Pipeline",
    "statuses": [
      {
        "label": "Draft"
      },
      {
        "label": "Confirmed",
        "color": "#22c55e"
      }
    ]
  }
}
```

Notes:

- TYPICAL AI FLOW to build a full custom entity: 1) createentity.json (this endpoint) with 'properties' AND 'statuses' in the SAME request -> the response 'created' maps every property name to its generated identifier (the default 'Name' included) and every status label to its 'st_...' id. 2) createrecord.json immediately, using those identifiers as field names in 'values' — send a value for EVERY entry with required:'y' ('Name' always is) and the status id in values.status_main — no schemas.json call needed. 3) getrecords.json / editrecord.json to work with records. saveproperty.json / savestatus.json are ONLY needed to add more fields/statuses LATER or to edit existing ones.
- VALIDATION is strict and upfront: every entry of 'properties' and 'statuses' is validated BEFORE anything is written — if any entry is invalid NOTHING is created and the error's 'failed_operation' points to the offending index (e.g. properties[2]). The rare 'partial_creation' error means the entity WAS created but a later step failed: continue with saveproperty.json instead of calling createentity again.
- The entity is ALWAYS born with a required 'Name' text property (auto-created — do NOT include it in 'properties'). It comes FIRST in the response 'created.properties' with required:'y': createrecord.json MUST receive a value for it.
- STATUSES: the first status of the list is the DEFAULT for new records (records created without a status get it). Records store the status 'id' ('st_...') in the group's docField ('status_main'): send values.status_main = 'st_...' in createrecord/editrecord. Add or edit statuses later with savestatus.json; reordering statuses in the CRM moves the default to the new first one.
- ASSOCIATIONS between entities are properties of type 'association' (targetEntity = the entity to link to, which must ALREADY exist — it cannot be the entity being created in this call). To link two NEW entities: create the target entity first, then this one with the association in its 'properties'; or create both and add the association afterwards with saveproperty.json.
- For date fields use type 'datetime': record values are ALWAYS stored as unix UTC epoch in SECONDS and shown in the CRM converted to each user's timezone.
- The response includes the sanitized 'entity' (every property with its identifier, statusgroups with ids, and the endpoint hints 'property_save', 'status_save', 'entity_edit', 'create', 'records', 'edit') — follow those hints instead of hardcoding routes.
- To rename the entity or change its icon/color later use /api/1.0/entities/editentity.json. To edit its records use /api/1.0/entities/editrecord.json.

### entities_save_property

`POST https://api.datalyse.io/api/1.0/entities/saveproperty.json`

Create OR edit ONE property (field) of a CUSTOM entity ('cust_...'). Without 'identifier' it CREATES a new property (the identifier is generated server-side and returned). With 'identifier' it EDITS that property (partial: only the fields you send change). THIS ENDPOINT IS ALSO THE TOOL TO CREATE ASSOCIATIONS between entities: send type 'association' with 'targetEntity' = the entitykey to link to ('leads', 'companies', another 'cust_...'); records then store the _id of the linked record in that property. One call per property — to add several fields to an EXISTING entity, call it once per field. The INITIAL fields of a NEW entity do not need this endpoint: /api/1.0/entities/createentity.json creates the entity with ALL its properties and statuses in ONE call. Allowed types: text, tags, textarea, select (REQUIRES 'options'), phone, email, number, datetime (date+time, ALWAYS stored as unix UTC epoch in SECONDS — use it for ANY date field; the old type 'date' can no longer be created), country, association (REQUIRES 'targetEntity'). The token's user must be master or admin.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. The linked user must be master or admin. Required. | YOUR_APIKEY |
| entitykey | string | yes | Key of the CUSTOM entity ('cust_...') to add/edit the property on. Required. | cust_ab12cd34ef56gh78 |
| identifier | string | no | Identifier of an EXISTING property to edit. OMIT to create a new property. (optional) |  |
| name | string | yes | Human name of the property. Required on create; on edit, only sent to rename. | Price |
| type | string | yes | Property type (create only; the type of an existing property can NEVER be changed): text, tags, textarea, select, phone, email, number, datetime, country, association. Defaults to 'text'. For dates use 'datetime': values are ALWAYS stored as unix UTC epoch in seconds and shown in the CRM converted to each user's timezone. | text |
| required | string | no | 'y' to make the property mandatory when creating records. (optional) | n |
| unique | string | no | 'y' to enforce unique values across records of the entity (not available for association). (optional) | n |
| options | array | no | REQUIRED for type select: array of options as plain strings (["Flat","House"]) or {text, textshow, selected:'y'\|'n'} objects; strings are normalized server-side to {text} objects. Record values must be the option 'text'. On edit: omit to keep current options (clearing is not supported); sending them REPLACES the whole list. Also accepts a JSON-encoded string. (optional) | Flat,House,Office |
| targetEntity | string | yes | REQUIRED for type association: entitykey this property points to ('leads', 'companies', 'opportunities', 'tasks', 'tickets', 'budgets' or another 'cust_...'). Must ALREADY exist. Cannot be changed on edit. | leads |
| cardinality | string | no | For type association: 'many-to-one' (default) or 'one-to-many'. (optional) | many-to-one |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/saveproperty.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"cust_ab12cd34ef56gh78","name":"Price","type":"text","required":"n","unique":"n","options":["Flat","House","Office"],"targetEntity":"leads","cardinality":"many-to-one"}'
```

Create a number field:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "name": "Price",
  "type": "number"
}
```

Create a select with options:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "name": "Type",
  "type": "select",
  "options": [
    "Flat",
    "House",
    "Office"
  ]
}
```

CREATE AN ASSOCIATION to contacts:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "name": "Owner",
  "type": "association",
  "targetEntity": "leads"
}
```

Edit: rename a property:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "identifier": "ab12777pricexk2m9q4t8w1z5c7",
  "name": "Sale price"
}
```

Edit: replace the options of a select:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "identifier": "ab12777typexk2m9q4t8w1z5c7v",
  "options": [
    "Flat",
    "House",
    "Office",
    "Garage"
  ]
}
```

Create a date+time field (stored as unix UTC epoch):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "name": "Signing date",
  "type": "datetime"
}
```

Notes:

- CREATING A NEW ENTITY? Do not chain saveproperty calls to build it: /api/1.0/entities/createentity.json accepts 'properties' (and 'statuses') and creates the FULL entity in ONE call. This endpoint is for adding fields to an entity that ALREADY exists or for editing them.
- CREATE: the property identifier is generated server-side (entity prefix + company id + name slug + random) and returned in 'identifier' — use it as the field name in createrecord/editrecord 'values'. New properties are visible in the record profile and tables by default.
- EDIT is PARTIAL and safe: only the parameters you send change (name, required, unique, options); everything else keeps its current value. 'type' and 'targetEntity' can NEVER be changed — create a new property instead. Omit 'options' to keep the current ones.
- ASSOCIATIONS: after creating a property of type 'association', link records by passing the _id string of the target record as that property's value in createrecord.json/editrecord.json (find ids with getrecords.json, which also returns human-readable 'assoclabels'). The entity's schema lists all its links in 'associations'.
- Values of 'select' properties must match one option 'text' exactly; changing options does NOT migrate existing records (old stored values remain and can be re-sent unchanged, but changing a record to an out-of-catalog value is rejected).
- The response always includes the full updated sanitized entity — no need to call schemas.json again.
- Property NAMES are not deduplicated: creating two properties named 'Price' is allowed and produces two distinct identifiers. Re-sending a create call after a network error therefore creates a DUPLICATE property — check the entity (schemas.json or the 'entity' of the previous response) before retrying.
- DATES: 'datetime' is the only date type ('date' was retired 2026-07-21; existing 'date' properties keep working with the same epoch contract). Record values accept unix UTC epoch in seconds (a millisecond epoch is auto-normalized) or 'yyyy-mm-dd' / 'yyyy-mm-dd hh:mm' strings — whatever you send, Mongo ALWAYS stores the unix UTC epoch, so ranges are filterable in getrecords.json with gt/gte/lt/lte just like creation_date.
- PROPERTY TYPES & VALUE FORMATS (what to send as the value of each property in createrecord/editrecord 'values'): text/textarea/phone/email -> string; number -> number (or numeric string); select -> the 'text' of one of the property's options (exact match; '' clears); tags -> array of strings (["vip","madrid"]); country -> lowercase ISO-2 code ('es', 'fr'); datetime (and legacy date) -> unix UTC epoch in SECONDS (preferred; ms auto-normalized; 'yyyy-mm-dd' and 'yyyy-mm-dd hh:mm' also accepted) — ALWAYS stored as epoch, shown in each user's timezone; association -> the _id string (24 hex chars) of the target record (find it with getrecords.json); status of the entity -> the status 'id' ('st_...') in the group's docField (usually values.status_main).

### entities_save_status

`POST https://api.datalyse.io/api/1.0/entities/savestatus.json`

Add OR edit ONE status of a CUSTOM entity ('cust_...'). Without 'id' it ADDS a new status: the FIRST status added to an entity automatically creates its status group (no separate call needed) and becomes the DEFAULT for new records. With 'id' (the 'st_...' id from schemas.json) it EDITS the label/color of an existing status. One call per status — to add several statuses to an EXISTING entity, call it once per status, in the order you want them displayed. The INITIAL statuses of a NEW entity can be created directly in /api/1.0/entities/createentity.json ('statuses' parameter). The token's user must be master or admin.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. The linked user must be master or admin. Required. | YOUR_APIKEY |
| entitykey | string | yes | Key of the CUSTOM entity ('cust_...'). Required. | cust_ab12cd34ef56gh78 |
| id | string | no | Id ('st_...') of an EXISTING status to edit. OMIT to add a new status. (optional) |  |
| label | string | yes | Status name. Required when adding; on edit, only sent to rename. | Available |
| color | string | no | Hex color of the status. (optional) | #22c55e |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/savestatus.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"cust_ab12cd34ef56gh78","label":"Available","color":"#22c55e"}'
```

Add the first status (creates the group, becomes the default):

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "label": "Available",
  "color": "#22c55e"
}
```

Add another status:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "label": "Sold",
  "color": "#ef4444"
}
```

Edit a status label:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "id": "st_1a2b3c4d5e6f7a8b",
  "label": "Reserved"
}
```

Notes:

- The status group of a custom entity is created AUTOMATICALLY with the first status you add (its docField is 'status_main'). The DEFAULT status is always the FIRST one in display order; reordering statuses in the CRM moves the default accordingly.
- Records store the status 'id' ('st_...') in the group's docField: to set a status when creating/editing a record, send values.status_main = 'st_...' in createrecord.json/editrecord.json (schemas.json shows the exact docField and every valid id). Records created without a status get the default one.
- The response returns 'status_id' (the id of the created/edited status) and the full updated sanitized entity — chain createrecord.json directly with that id, no extra schemas.json call needed.
- Initial statuses — and initial PROPERTIES — can be created directly when creating the entity: createentity.json builds the FULL entity in one call. This endpoint is for adding MORE statuses later or editing existing ones.

### entities_edit_entity

`POST https://api.datalyse.io/api/1.0/entities/editentity.json`

Edit the METADATA of an entity: rename it (name, name_plural) or change its icon/color. Works on custom entities ('cust_...') and on built-in ones (renaming 'leads' to 'Patients', for example). ONLY metadata: to create/edit PROPERTIES (fields, including associations) use POST /api/1.0/entities/saveproperty.json, and to add/edit STATUSES use POST /api/1.0/entities/savestatus.json — this endpoint rejects the old 'addproperties'/'editproperties'/'addstatuses'/'editstatuses' parameters with use_dedicated_endpoints. The token's user must be master or admin.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. The linked user must be master or admin. Required. | YOUR_APIKEY |
| entitykey | string | yes | Key of the entity to edit: 'cust_...' or a built-in key (leads, companies, opportunities, tasks, tickets, budgets). Required. | cust_ab12cd34ef56gh78 |
| name | string | no | New singular name. (optional) | Property |
| name_plural | string | no | New plural name. (optional) | Properties |
| icon | string | no | New Tabler icon class. (optional) | ti ti-home |
| color | string | no | New hex color. (optional) | #16a34a |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/entities/editentity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","entitykey":"cust_ab12cd34ef56gh78","name":"Property","name_plural":"Properties","icon":"ti ti-home","color":"#16a34a"}'
```

Rename an entity:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "name": "Home",
  "name_plural": "Homes"
}
```

Change icon and color:

```json
{
  "token": "YOUR_APIKEY",
  "entitykey": "cust_ab12cd34ef56gh78",
  "icon": "ti ti-building",
  "color": "#7c3aed"
}
```

Notes:

- The entitykey and the physical storage never change, even when renaming.
- The response always includes the full updated sanitized entity.
- Properties: /api/1.0/entities/saveproperty.json (one call per property; type association creates links between entities). Statuses: /api/1.0/entities/savestatus.json (one call per status). Records: /api/1.0/entities/editrecord.json.

## Leads

### create_lead

`POST https://api.datalyse.io/api/1.0/leads/create.json`

Create a new contact or company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| agent_id | string | no | Set to "unassigned" to assign this lead to all agents, or provide a specific agent_id to assign it to an agent (optional) |  |
| leadtypedatal | string | no | Identifier of the contact or company type (optional) |  |
| ESCOMPANIES | string | no | Set to "y" if it is a company (optional) |  |
| status | string | yes | Status ID | 0 |
| name | string | yes | Name for the contact | Marc |
| lastname | string | yes | Last name | Doe |
| phone | string | yes | Phone with international prefix | 34682288888 |
| email | string | yes | Email | example@exampleemail.com |
| country | string | yes | Country ISO code | es |
| add_note | string | no | Add a note to this contact or company (optional) |  |
| in_leadcompany | string | no | ID of the company this contact belongs to (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/create.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","status":"0","name":"Marc","lastname":"Doe","phone":"34682288888","email":"example@exampleemail.com","country":"es"}'
```

### edit_lead

`POST https://api.datalyse.io/api/1.0/leads/edit.json`

Edit a contact or company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| lead_id | string | yes | ID of the contact or company to edit |  |
| agent_id | string | no | Set to "unassigned" to assign this lead to all agents, or provide a specific agent_id to assign it to an agent (optional) |  |
| status | string | yes | Status ID | 0 |
| name | string | yes | Name of the contact or company | Marc |
| lastname | string | yes | Last name | Doe |
| phone | string | yes | Phone number with international prefix | 34682288888 |
| email | string | yes | Email | example@exampleemail.com |
| country | string | yes | Country ISO code | es |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","lead_id":"","status":"0","name":"Marc","lastname":"Doe","phone":"34682288888","email":"example@exampleemail.com","country":"es"}'
```

### delete_lead

`POST https://api.datalyse.io/api/1.0/leads/delete.json`

Delete a contact or company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| lead_id | string | yes | ID of the contact or company to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","lead_id":""}'
```

### get_leads

`POST https://api.datalyse.io/api/1.0/leads/get.json`

Get a list of contacts or companies

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| var_status | string | no | Show only results with this status (optional) |  |
| var_agentfilter | string | no | Show only results for this agent ID (optional) |  |
| search_value | string | no | Text to search for (optional) |  |
| filter_types | string | no | Filter type for the search value (optional) |  |
| datefrom | string | no | Start date for filtering results (optional, format: YYYY-MM-DD, example: 2026-01-01). Requires dateto and timezone to apply. |  |
| dateto | string | no | End date for filtering results (optional, format: YYYY-MM-DD, example: 2026-12-31). Requires datefrom and timezone to apply. |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid). Required together with datefrom and dateto. | Europe/Madrid |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1","timezone":"Europe/Madrid"}'
```

### add_note_to_lead

`POST https://api.datalyse.io/api/1.0/leads/addnote.json`

Add a note to the contact or company

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| lead_id | string | yes | ID of the contact or company |  |
| text | string | yes | Text of the note | Hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/addnote.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","lead_id":"","text":"Hello world"}'
```

### get_lead_activity

`POST https://api.datalyse.io/api/1.0/leads/getactivity.json`

Get activity/timeline for a contact

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| lead_id | string | yes | ID of the contact |  |
| type | string | no | Filter by activity type: callin, callout, email, emailin, emailout, note, sms, form_completed, etc. (optional) |  |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/leads/getactivity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","lead_id":"","var_resultspage":"20","var_page":"1"}'
```

## Notifications

### notifications_list

`POST https://api.datalyse.io/api/1.0/notifications/list.json`

Get notifications for the authenticated agent with pagination

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Results per page (default 20) | 20 |
| var_page | string | yes | Page number (default 1) | 1 |
| read | string | no | Filter by read status: 0 for unread, 1 for read (optional, returns all by default) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/notifications/list.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### notifications_sendpush

`POST https://api.datalyse.io/api/1.0/notifications/sendpush.json`

Send a push notification to an agent. Same logic as workflows sendnoti block

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| title | string | yes | Notification title |  |
| text | string | yes | Notification text/body |  |
| target_agent_id | string | no | Agent ID to send the notification to (optional, defaults to self) |  |
| assign_to | string | yes | Set to 'current' to send to the lead's owner agent (requires id_lead) |  |
| id_lead | string | no | Lead ID to link in the notification and resolve owner agent (optional) |  |
| type | string | yes | Notification type (default 'noti') | noti |
| badge | string | yes | Badge letter shown in notification (default 'L') | L |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/notifications/sendpush.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","title":"","text":"","assign_to":"","type":"noti","badge":"L"}'
```

### notifications_read

`POST https://api.datalyse.io/api/1.0/notifications/read.json`

Mark one or all notifications as read

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| notification_id | string | no | ID of a single notification to mark as read (optional if read_all is used) |  |
| read_all | string | yes | Set to 'y' to mark all notifications as read |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/notifications/read.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","read_all":""}'
```

## Opportunities

### create_opportunity

`POST https://api.datalyse.io/api/1.0/opportunities/create.json`

Create a new opportunity

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| agent_id | string | no | Agent ID (optional) | unassigned |
| lead_id | string | yes | ID of the contact or company |  |
| description | string | yes | Description of the opportunity | New opportunity |
| amount | string | yes | Total amount | 10 |
| currency | string | yes | Currency | eur |
| status | string | yes | Status ID | 0 |
| statusd | string | no | Stage (optional) |  |
| pipeline | string | no | Pipeline ID (optional) |  |
| expecteddate | string | no | Expected closing date and time in ONE field: unix timestamp in SECONDS, not milliseconds. The timezone MUST be UTC (optional, recommended; example: 1789041600 = 2026-09-10T12:00:00Z). Convert the user's local time to UTC before sending. Legacy 'YYYY-MM-DD' string also accepted combined with 'time' — legacy values MUST be in UTC too. | 1789041600 |
| time | string | no | Legacy: time HH:MM in UTC, only used when expecteddate is sent as 'YYYY-MM-DD' (optional) |  |
| calendar_id | string | no | Calendar task ID (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/create.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","agent_id":"unassigned","lead_id":"","description":"New opportunity","amount":"10","currency":"eur","status":"0","expecteddate":"1789041600"}'
```

### get_opportunities

`POST https://api.datalyse.io/api/1.0/opportunities/get.json`

Get a list of opportunities. Each result includes 'expecteddate': expected closing date+time as a unix timestamp in SECONDS, timezone UTC (example: 1789041600 = 2026-09-10T12:00:00Z).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| var_status | string | no | Show only results with this status (optional) |  |
| var_agentfilter | string | no | Show only results for this agent ID (optional) |  |
| search_value | string | no | Text to search for (optional) |  |
| datefrom | string | no | Start date for filtering results (optional, format: YYYY-MM-DD) |  |
| dateto | string | no | End date for filtering results (optional, format: YYYY-MM-DD) |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### edit_opportunity

`POST https://api.datalyse.io/api/1.0/opportunities/edit.json`

Edit an opportunity

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| opportunity_id | string | yes | ID of the opportunity to edit |  |
| description | string | no | Description of the opportunity (optional) |  |
| amount | string | no | Total amount (optional) |  |
| currency | string | no | Currency (optional) |  |
| status | string | no | Status ID (optional) |  |
| pipeline | string | no | Pipeline ID (optional) |  |
| expecteddate | string | no | Expected closing date and time in ONE field: unix timestamp in SECONDS, not milliseconds. The timezone MUST be UTC (optional, recommended; example: 1789041600 = 2026-09-10T12:00:00Z). Convert the user's local time to UTC before sending. Legacy 'YYYY-MM-DD' string also accepted combined with 'time' — legacy values MUST be in UTC too. | 1789041600 |
| time | string | no | Legacy: time HH:MM in UTC, only used when expecteddate is sent as 'YYYY-MM-DD' (optional) |  |
| agent_id | string | no | Agent ID or "unassigned" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","opportunity_id":"","expecteddate":"1789041600"}'
```

### delete_opportunity

`POST https://api.datalyse.io/api/1.0/opportunities/delete.json`

Delete an opportunity

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| opportunity_id | string | yes | ID of the opportunity to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","opportunity_id":""}'
```

### add_note_to_opportunity

`POST https://api.datalyse.io/api/1.0/opportunities/addnote.json`

Add a note to an opportunity

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| opportunity_id | string | yes | ID of the opportunity |  |
| text | string | yes | Text of the note | Hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/addnote.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","opportunity_id":"","text":"Hello world"}'
```

### get_opportunity_activity

`POST https://api.datalyse.io/api/1.0/opportunities/getactivity.json`

Get activity/timeline for an opportunity

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| opportunity_id | string | yes | ID of the opportunity |  |
| type | string | no | Filter by activity type (optional) |  |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/opportunities/getactivity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","opportunity_id":"","var_resultspage":"20","var_page":"1"}'
```

## Payments

### create_payment

`POST https://api.datalyse.io/api/1.0/payments/create.json`

Create a new payment record

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| agent_id | string | yes | Agent ID |  |
| id_lead | string | yes | ID of the contact or company |  |
| fromagent_id | string | yes | Agent ID who created the payment |  |
| ispayment | string | yes | Payment type flag |  |
| mt4_transtype | string | yes | Transaction type |  |
| name | string | yes | Payment name or description |  |
| mt4user | string | no | MT4 user ID (optional) |  |
| amount | string | yes | Payment amount | 0 |
| amount_usd | string | no | Amount in USD (optional) |  |
| amount_eur | string | no | Amount in EUR (optional) |  |
| currency | string | yes | Currency code | eur |
| netcurrency | string | no | Net currency (optional) |  |
| comission | string | no | Commission amount (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/payments/create.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","agent_id":"","id_lead":"","fromagent_id":"","ispayment":"","mt4_transtype":"","name":"","amount":"0","currency":"eur"}'
```

### get_payments

`POST https://api.datalyse.io/api/1.0/payments/get.json`

Get a paginated list of payments/credits for the authenticated company. Supports filtering by payment type, lead, agent, and date range (datefrom/dateto/timezone). Dates are filtered against the payment 'date' field (unix timestamp in seconds). Use this to answer questions like 'show me payments last month', 'list credits for lead X', or 'how many payments did agent Y process in January'.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| ispayment | string | no | Filter by type: "y" for payments, "n" for credits (optional) |  |
| id_lead | string | no | Filter by lead ID (optional) |  |
| agent_id | string | no | Filter by agent ID (optional) |  |
| datefrom | string | no | Start date for filtering results by payment date (optional, format: YYYY-MM-DD, example: 2026-01-01). Requires dateto and timezone to apply. |  |
| dateto | string | no | End date for filtering results by payment date (optional, format: YYYY-MM-DD, example: 2026-12-31). Requires datefrom and timezone to apply. |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid). Required together with datefrom and dateto. |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/payments/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### edit_payment

`POST https://api.datalyse.io/api/1.0/payments/edit.json`

Edit a payment

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| payment_id | string | yes | ID of the payment to edit |  |
| name | string | no | Payment name (optional) |  |
| agent_id | string | no | Agent ID (optional) |  |
| amount | string | no | Payment amount (optional) |  |
| amount_usd | string | no | Amount in USD (optional) |  |
| amount_eur | string | no | Amount in EUR (optional) |  |
| currency | string | no | Currency code (optional) |  |
| ispayment | string | no | Payment type flag (optional) |  |
| mt4_transtype | string | no | Transaction type (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/payments/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","payment_id":""}'
```

### delete_payment

`POST https://api.datalyse.io/api/1.0/payments/delete.json`

Delete a payment (soft delete)

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| payment_id | string | yes | ID of the payment to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/payments/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","payment_id":""}'
```

## Phonenumbers

### phonenumbers_get_countries

`GET https://api.datalyse.io/api/1.0/phonenumbers/countries.json`

Get all countries with phone numbers available for purchase: ISO code, name, phone prefix, available number types and how many area groups each one has. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/countries.json?token=YOUR_APIKEY'
```

### phonenumbers_get_did_groups

`GET https://api.datalyse.io/api/1.0/phonenumbers/did_groups.json`

Get purchasable number groups (area codes) of a country with client prices in EUR. Each group lists its SKUs (capacity plans): setup and monthly price, included channels, per-minute incoming cost (coste_xmin/coste_xllam, 0 for flat-rate plans) and whether the plan is sellable. needs_registration=true means identity documents are required after purchase. Global/UIFN groups are returned for any country. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| country | string | yes | Country ISO2 code (e.g. ES, GB, US) | ES |
| type | string | no | Filter by group type: Local, National, Mobile, Toll-free, Shared Cost, Global (optional) |  |
| q | string | no | Search by area name or prefix (optional) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/did_groups.json?token=YOUR_APIKEY&country=ES&type=&q='
```

### phonenumbers_get_available_dids

`GET https://api.datalyse.io/api/1.0/phonenumbers/available_dids.json`

Get the specific numbers available to pick inside a DID group (live from the provider). If the list is empty a new random number can still be ordered (new_number_available is always true). Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| did_group | string | yes | DID group id (from did_groups.json) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/available_dids.json?token=YOUR_APIKEY&did_group='
```

### phonenumbers_order

`POST https://api.datalyse.io/api/1.0/phonenumbers/order.json`

Buy a phone number: creates the order at the provider, charges the voice credit balance and assigns the line to a PBX (creates a new PBX with a default IVR if none is given). If needs_registration is true the number requires identity verification (see requirements, identity and identity_submit endpoints). The line starts as activating (estado 0) and switches to active automatically when the provider confirms. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| did_group_id | string | yes | DID group id (from did_groups.json) |  |
| sku_id | string | yes | Capacity plan SKU id of the group (from did_groups.json, only sellable SKUs) |  |
| available_did_id | string | no | Specific number picked from available_dids.json; omit to get a new random number (optional) |  |
| idcampanadondecrear | integer | no | PBX id where to attach the number; omit to create a new PBX with a default IVR (optional) |  |
| lang | string | no | 2-letter language for the default IVR TTS voice when a new PBX is created (optional, default en) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/order.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","did_group_id":"","sku_id":""}'
```

### phonenumbers_get_requirements

`GET https://api.datalyse.io/api/1.0/phonenumbers/requirements.json`

Get the regulatory registration requirements of a DID group: accepted identity/address proof types, mandatory identity fields and permanent document templates. Returns needs_registration=false with an empty list when no registration is needed. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| did_group_id | string | yes | DID group id (from did_groups.json) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/requirements.json?token=YOUR_APIKEY&did_group_id='
```

### phonenumbers_create_identity

`POST https://api.datalyse.io/api/1.0/phonenumbers/identity.json`

Create a regulatory identity with its address at the provider (needed for numbers with needs_registration). Returns identity_id and address_id to use with identity_document.json and identity_submit.json. The identity is saved and reusable for future numbers (see identities_list.json). Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| identity.identity_type | string | yes | Identity type: personal or business | personal |
| identity.first_name | string | yes | First name (or legal representative for business) |  |
| identity.last_name | string | yes | Last name |  |
| identity.phone_number | string | yes | Contact phone number with international prefix |  |
| identity.company_name | string | yes | Company name (business identities) |  |
| identity.company_reg_number | string | yes | Company registration number (if required by the country) |  |
| identity.vat_id | string | yes | VAT id (if required by the country) |  |
| identity.personal_tax_id | string | yes | Personal tax id (if required by the country) |  |
| identity.id_number | string | yes | Personal id/passport number (if required by the country) |  |
| identity.birth_date | string | yes | Birth date YYYY-MM-DD (if required by the country) |  |
| identity.contact_email | string | no | Contact email (optional) |  |
| address.country_iso | string | yes | Address country ISO2 code | ES |
| address.city_name | string | yes | City |  |
| address.postal_code | string | yes | Postal code |  |
| address.address | string | yes | Street address |  |
| address.description | string | no | Address description (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/identity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","identity.identity_type":"personal","identity.first_name":"","identity.last_name":"","identity.phone_number":"","identity.company_name":"","identity.company_reg_number":"","identity.vat_id":"","identity.personal_tax_id":"","identity.id_number":"","identity.birth_date":"","address.country_iso":"ES","address.city_name":"","address.postal_code":"","address.address":""}'
```

### phonenumbers_list_identities

`GET https://api.datalyse.io/api/1.0/phonenumbers/identities_list.json`

List the client's saved regulatory identities with their addresses and verification status, to reuse them when registering another number. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/identities_list.json?token=YOUR_APIKEY'
```

### phonenumbers_create_address

`POST https://api.datalyse.io/api/1.0/phonenumbers/address.json`

Add an additional address to one of the client's existing regulatory identities (identity reuse for a number in another city/country). Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| identity_id | string | yes | Identity id owned by the client (from identities_list.json) |  |
| address.country_iso | string | yes | Address country ISO2 code | ES |
| address.city_name | string | yes | City |  |
| address.postal_code | string | yes | Postal code |  |
| address.address | string | yes | Street address |  |
| address.description | string | no | Address description (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/address.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","identity_id":"","address.country_iso":"ES","address.city_name":"","address.postal_code":"","address.address":""}'
```

### phonenumbers_upload_identity_document

`POST https://api.datalyse.io/api/1.0/phonenumbers/identity_document.json`

Upload a verification document (multipart form-data, field name: file; pdf/jpg/png, max 20MB). The file is encrypted client-side before being sent to the provider. kind=proof_identity links it to an identity (needs proof_type_id), kind=proof_address to an address (needs proof_type_id and address_id), kind=permanent_document to a permanent template (needs template_id). Proof type and template ids come from requirements.json. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| file | file | yes | Document file (multipart form-data; pdf, jpg or png, max 20MB) |  |
| kind | string | yes | Document kind: proof_identity, proof_address or permanent_document | proof_identity |
| identity_id | string | yes | Identity id owned by the client (required for proof_identity and permanent_document) |  |
| proof_type_id | string | yes | Proof type id from requirements.json (required for proof_identity and proof_address) |  |
| address_id | string | yes | Address id the proof belongs to (required for proof_address) |  |
| template_id | string | yes | Permanent document template id from requirements.json (required for permanent_document) |  |
| description | string | no | File description (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/identity_document.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","file":"","kind":"proof_identity","identity_id":"","proof_type_id":"","address_id":"","template_id":""}'
```

### phonenumbers_submit_identity

`POST https://api.datalyse.io/api/1.0/phonenumbers/identity_submit.json`

Submit the address verification of a purchased number for provider review. Optionally pre-validates against the address requirement so missing data is reported instantly (validation_failed) instead of days later as a rejection. On approval the line is activated automatically and the user gets a push notification. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| did_id | string | yes | DID id of the purchased number (returned by order.json) |  |
| address_id | string | yes | Address id of one of the client's identities |  |
| identity_id | string | no | Identity id, when the address alone is ambiguous (optional) |  |
| address_requirement_id | string | no | Address requirement id from requirements.json to pre-validate before submitting (optional, recommended) |  |
| service_description | string | no | Short description of the service using the number (optional, default: CRM phone line) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/identity_submit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","did_id":"","address_id":""}'
```

### phonenumbers_get_identity_status

`GET https://api.datalyse.io/api/1.0/phonenumbers/identity_status.json`

Get the live verification status of a number registration (pending, approved or rejected with reject reasons). If the provider already approved it, the line is activated on the spot. Pass did_id or verification_id. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| did_id | string | yes | DID id of the number (alternative to verification_id) |  |
| verification_id | string | yes | Verification id returned by identity_submit.json (alternative to did_id) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/identity_status.json?token=YOUR_APIKEY&did_id=&verification_id='
```

### phonenumbers_get_pending_registrations

`GET https://api.datalyse.io/api/1.0/phonenumbers/pending_registrations.json`

Get the client's numbers with identity registration pending (not sent, in review or rejected) plus the numbers still activating (bought without registration, waiting for provider confirmation, last 72h). Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/pending_registrations.json?token=YOUR_APIKEY'
```

### phonenumbers_get_capacity_info

`GET https://api.datalyse.io/api/1.0/phonenumbers/capacity_info.json`

Get the current channel capacity of a phone line (included and dedicated channels) and the monthly price per extra dedicated channel in EUR. pool_disponible=false means extra channels are not available for that country. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| phoneline | string | yes | Phone line number (digits only, with country prefix) | 34930000000 |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/phonenumbers/capacity_info.json?token=YOUR_APIKEY&phoneline=34930000000'
```

### phonenumbers_contract_channels

`POST https://api.datalyse.io/api/1.0/phonenumbers/contract_channels.json`

Buy extra dedicated channels for a phone line (1 to 50). Charges the voice credit balance, expands the DID capacity at the provider and adds the price to the line's monthly renewal. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| phoneline | string | yes | Phone line number (digits only, with country prefix) | 34930000000 |
| channels | integer | yes | Number of dedicated channels to add (1-50) | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/contract_channels.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","phoneline":"34930000000","channels":"1"}'
```

### phonenumbers_move

`POST https://api.datalyse.io/api/1.0/phonenumbers/move.json`

Move a phone number to another PBX of the same client, or create a new PBX (with a default IVR) and move it there. Identify the line with phoneline or id_alias; set to_pbx_id for an existing PBX or new_pbx=true to create one. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| phoneline | string | yes | Phone line number to move (alternative to id_alias) | 34930000000 |
| id_alias | integer | yes | Internal line id (alternative to phoneline) |  |
| to_pbx_id | integer | yes | Destination PBX id (required unless new_pbx is true) |  |
| new_pbx | boolean | yes | Set to true to create a new PBX and move the number there |  |
| new_pbx_name | string | no | Name for the new PBX (optional, only with new_pbx) |  |
| lang | string | no | 2-letter language for the new PBX default IVR TTS voice (optional, default en) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/move.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","phoneline":"34930000000","id_alias":"","to_pbx_id":"","new_pbx":""}'
```

### phonenumbers_clone_pbx

`POST https://api.datalyse.io/api/1.0/phonenumbers/clone_pbx.json`

Clone a PBX: campaign, configuration and all call-flow nodes (node links are remapped). Phone numbers are NOT cloned. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| pbx_id | integer | yes | PBX id to clone (must belong to the client) |  |
| new_name | string | no | Name for the cloned PBX (optional, default: original name + (copy)) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/clone_pbx.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","pbx_id":""}'
```

### phonenumber_delete

`POST https://api.datalyse.io/api/1.0/phonenumbers/delete.json`

Cancel a phone line: terminates the number at the provider and removes the line. The purchase is refunded in credits only if cancelled the same month it was bought. The cancellation is irreversible. Requires phone numbers management permission.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| phoneline | string | yes | Phone line number to cancel (digits only, with country prefix) | 34930000000 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/phonenumbers/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","phoneline":"34930000000"}'
```

## Sendsms

### send_sms

`POST https://api.datalyse.io/api/1.0/sendsms/smsmt.json`

Send a transactional SMS (SMS-MT, mobile terminated) to a single phone number through the company's SMS provider. Use this when the user asks to send an SMS, a short text, a verification code, an OTP, a reminder, a notification or any text message to a phone number. Before calling this, the caller must already know the destination phone number in international format (country code + number, no '+' or spaces), the text body, and a 'from' sender ID (alphanumeric up to 11 chars, e.g. 'MyCompany', or a numeric shortcode). If you do not have a valid sender, ask the user which 'from' to use — do NOT invent one. To estimate the cost per destination country before sending, call /api/1.0/sendsms/prices.json first. Optionally attach a lead_id so the message is logged inside that lead's timeline.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| to | string | yes | Recipient phone number in international format, digits only, with country code and no '+' sign or spaces (e.g. 34600000000 for Spain, 14155552671 for USA). Required. | 34682288834 |
| from | string | yes | Sender ID displayed to the recipient. Alphanumeric up to 11 characters (e.g. 'Datalyse', 'Acme'), or a numeric shortcode. Some carriers strip or rewrite alphanumeric senders — ask the user for a valid one if unsure. Required. | testfrom |
| text | string | yes | UTF-8 body of the SMS. Keep under 160 GSM-7 characters to fit in one segment; longer texts are split into multiple segments and billed per segment. Required. | hello world |
| lead_id | string | no | Optional Mongo ObjectId of the lead to attach this SMS to. When provided, the message is stored inside that lead's activity timeline. Optional. |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendsms/smsmt.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","to":"34682288834","from":"testfrom","text":"hello world"}'
```

### get_sms_prices

`GET https://api.datalyse.io/api/1.0/sendsms/prices.json`

Get SMS pricing list, optionally filtered by country

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| country | string | no | Country ISO code to filter prices (optional) |  |

Example:

```bash
curl 'https://api.datalyse.io/api/1.0/sendsms/prices.json?token=YOUR_APIKEY&country='
```

## Sendvoicecall

### sendvoicecall_listaiagents

`POST https://api.datalyse.io/api/1.0/sendvoicecall/listaiagents.json`

List every AI voice agent configured for this company. Call this BEFORE /api/1.0/sendvoicecall/createcall.json, because creating an AI call batch requires a valid 'agent_ai_id' — that id is the _id of one of the agents returned here. The response includes each agent's name, language, voice, system prompt summary and knowledge base so the caller can pick the agent that best fits the call's purpose (sales, support, appointment reminder, etc.). Does not place any call by itself.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendvoicecall/listaiagents.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### sendvoicecall_createcall

`POST https://api.datalyse.io/api/1.0/sendvoicecall/createcall.json`

Create a new AI voice call batch campaign that will phone one or more recipients using an AI agent. Use this when the user wants the system to actually place outbound phone calls (e.g. 'call these leads', 'phone these customers', 'launch a reminder call campaign'). MANDATORY WORKFLOW: (1) call /api/1.0/sendvoicecall/listaiagents.json to pick the right 'agent_ai_id' for the campaign's purpose; (2) call /api/1.0/companyuserdata/callerids.json to pick a valid 'caller_id' (one of the company's phone lines allowed to place outbound calls); (3) build the 'recipients' array with one entry per person to call, each with phone (international format, digits only), name and country ISO code. Optionally schedule the campaign: set mode='schedule' plus start_date/start_time/end_time/timezone, or mode='immediately' to dial as soon as the worker picks it up. Returns a batch_id that can be later used with getone.json, stop.json, pause.json and unpause.json. Never invent phone numbers — only use the ones the user explicitly provided or the ones retrieved from a previous query.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| agent_ai_id | string | yes | Mongo ObjectId of the AI voice agent that will conduct the calls. Obtain from /api/1.0/sendvoicecall/listaiagents.json. Required. |  |
| caller_id | string | yes | Phone number (caller id) the AI will dial out from. Must be one of the callerids available to the company — obtain from /api/1.0/companyuserdata/callerids.json. Can also be a shared caller id in the format 'compartido 999id_campana'. Required. |  |
| batch_name | string | no | Human-readable name for this call batch (shown in the UI and reports). Optional. |  |
| recipients | array | yes | JSON array of call targets. Each element is an object with three string fields: 'phone' (international format, digits only, no '+' and no spaces, e.g. 34660558411), 'name' (display name, e.g. Marc) and 'country' (ISO 3166-1 alpha-2 lowercase, e.g. es, us, mx). At least one recipient is required. Pass it as a real JSON array of objects — do NOT wrap it in a string. See the 'default' field for a concrete example. | [object Object],[object Object] |
| mode | string | yes | Dispatch mode. 'immediately' (default) starts dialing as soon as the worker picks up the batch; 'schedule' uses the start_date/start_time/end_time/timezone fields below. Required. | immediately |
| timezone | string | no | IANA timezone for start_date/start_time/end_time when mode='schedule' (e.g. 'Europe/Madrid', 'America/Mexico_City'). Optional, defaults to 'UTC'. | UTC |
| start_date | string | no | Date the campaign can start dialing, in YYYY-MM-DD format. Only used when mode='schedule'. Optional, defaults to today. |  |
| start_time | string | no | Earliest hour of the day at which the AI is allowed to place calls, in 24h HH:MM format. Only used when mode='schedule'. Optional, defaults to '10:00'. | 10:00 |
| end_time | string | no | Latest hour of the day at which the AI is allowed to place calls, in 24h HH:MM format. Only used when mode='schedule'. Optional, defaults to '19:00'. | 19:00 |
| rate_per_minute | string | no | Maximum number of simultaneous new calls the dialer is allowed to open per minute. Use to throttle spend and avoid carrier rate-limits. Optional, defaults to '30'. | 30 |
| date_start_ms | string | no | Alternative to start_date/start_time: absolute Unix timestamp in MILLISECONDS (UTC) at which dialing should begin. Optional. |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendvoicecall/createcall.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","agent_ai_id":"","caller_id":"","recipients":[{"name":"marc","phone":"34660558411","country":"es"},{"name":"James","phone":"34682288834","country":"es"}],"mode":"immediately","timezone":"UTC","start_time":"10:00","end_time":"19:00","rate_per_minute":"30"}'
```

## Sendwhatsapp

### whatsapp_get_sessions_and_templates

`POST https://api.datalyse.io/api/1.0/sendwhatsapp/getsessionsandtemplates.json`

List every WhatsApp Business session connected to this company and, for each session, its approved Meta-hosted templates. Call this BEFORE using /api/1.0/sendwhatsapp/sendmsgtemplate.json, sendmsg.json or sendfile.json, because you need a valid 'idses' (session _id) to send anything, and for templates you also need to know the exact 'name', 'language' and the 'components' array (which defines what {{1}}, {{2}}... variables each template expects, and whether the HEADER is TEXT/IMAGE/VIDEO/DOCUMENT). Returns only the fields needed for dispatch: each session's _id and name, plus a whats_templates[] array with the template name, language, status, category, id and components. The caller must then pick the right session and template based on what the user wants to send.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendwhatsapp/getsessionsandtemplates.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY"}'
```

### sendwhatsapp_sendmsgtemplate

`POST https://api.datalyse.io/api/1.0/sendwhatsapp/sendmsgtemplate.json`

Send a pre-approved WhatsApp Business template message directly through the Meta Cloud API and return Meta's response synchronously (including the delivered message wamid on success, or Meta's error on failure). Use this to start conversations outside the 24-hour customer service window, to send transactional notifications (OTP, order updates, shipping, reminders), or to re-engage a lead when the free-form chat window is closed. MANDATORY WORKFLOW: (1) first call /api/1.0/sendwhatsapp/getsessionsandtemplates.json to discover the sessions and their approved templates; (2) pick the session 'idses' the user wants to send from and the exact 'template_name' that matches the intent; (3) inspect that template's 'components' array — if any component contains {{1}}, {{2}}, {{3}}... body variables, pass the matching values inside the simplified 'variables' field (the server auto-inspects the template and places each value in the correct Meta slot — you do NOT need to build the Meta components array yourself). If the template has ZERO body variables and no TEXT header variable, simply omit 'variables' entirely. IMPORTANT — MEDIA HEADERS (IMAGE/VIDEO/DOCUMENT): do NOT ask the user for a media URL and do NOT send 'variables.header' for these. The server auto-loads the media from the file that was originally uploaded with the template (infinitycloud), falling back to Meta's stored example. Only pass 'variables.header' as a media URL if the user explicitly asks to override the template's attached file with a different one. Never invent variable values — if the user did not provide body/text values, ask first. Unlike the old queue-based behaviour, this endpoint now POSTs to Meta synchronously: a successful response returns 'wamid' from Meta, and a failure returns status:'error' with the Meta error embedded.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| idses | string | yes | WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the message. Obtain it from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required. |  |
| to | string | yes | Recipient phone number in full international format, digits only, no '+' sign, no spaces, no dashes (e.g. 34600000000). Required. | 34682288834 |
| template_name | string | yes | Exact 'name' field of the approved WhatsApp template to send (e.g. 'datalysewowia'). Must be one of the templates returned by getsessionsandtemplates for the chosen session. Required. |  |
| language | string | no | Template language code (e.g. 'es', 'en_US', 'pt_BR'). Optional: defaults to the template's own language. Only override it if you know the same template has multiple approved translations. |  |
| variables | object | yes | Simplified template variables — the server auto-inspects the approved template's components and places each value in the correct Meta slot, so you do NOT build the Meta components array yourself. Shape: an object with any of these keys — 'body' is an array of strings matching the template BODY's {{1}},{{2}},... placeholders in order (e.g. body:['Marc','OFFER105']); 'header' is used ONLY when the template HEADER is TEXT with a {{1}} variable (value is the plain text) OR when the caller wants to explicitly override an IMAGE/VIDEO/DOCUMENT media template with a different public URL (normally you should NOT send 'header' for media templates — the server auto-loads the file that was uploaded with the template); 'button' is an array of URL-button values where each element is either a plain string or an object {index:N, payload:'...'} for button parameter {{1}}. Shortcuts: pass a bare array of strings (['123456','Marc']) to fill only body variables, or a bare string ('123456') for a single body variable. Count and order of 'body' entries MUST match the {{n}} placeholders in the template's BODY text — use /api/1.0/sendwhatsapp/getsessionsandtemplates.json to inspect the template first. Omit this field entirely when the template has no body variables. | [object Object] |
| components | array | no | ADVANCED / OPTIONAL escape hatch. Pre-built Meta Cloud API components array in the exact Meta shape (entries like {type:'body', parameters:[{type:'text', text:'...'}]}). Only use this if you are replicating an existing hand-crafted Meta payload — normally you should use the simpler 'variables' field instead and let the server build the components automatically. If both 'components' and 'variables' are provided, 'components' wins. | [object Object] |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendwhatsapp/sendmsgtemplate.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","idses":"","to":"34682288834","template_name":"","variables":{"body":["123456"]},"components":[{"type":"body","parameters":[{"type":"text","text":"HOLA"}]}]}'
```

Template WITHOUT variables:

```json
{
  "token": "YOUR_APIKEY",
  "idses": "6797065fdfec41b50d649e64",
  "to": "34660558411",
  "template_name": "sample_template"
}
```

Template with ONE body variable {{1}} (simplified 'variables'):

```json
{
  "token": "YOUR_APIKEY",
  "idses": "6797065fdfec41b50d649e64",
  "to": "34660558411",
  "template_name": "authcodenow",
  "variables": [
    "123456"
  ]
}
```

Template with TEXT header variable + body variables (simplified 'variables'):

```json
{
  "token": "YOUR_APIKEY",
  "idses": "6797065fdfec41b50d649e64",
  "to": "34660558411",
  "template_name": "datalysewowia",
  "variables": {
    "header": "Header value",
    "body": [
      "Marc",
      "OFFER105"
    ]
  }
}
```

Template with BODY variable only (re-engage after 24h):

```json
{
  "token": "YOUR_APIKEY",
  "idses": "YOUR_SESSION_ID",
  "to": "34600000000",
  "template_name": "mensajecuandopasanlas24holacomoestas",
  "variables": [
    "HOLA"
  ]
}
```

Template with VIDEO/IMAGE/DOCUMENT header — no 'variables.header' needed:

```json
{
  "token": "YOUR_APIKEY",
  "idses": "YOUR_SESSION_ID",
  "to": "34600000000",
  "template_name": "templatenewfeatureannouncement",
  "language": "es"
}
```

Template with media header + body variables + URL button (media auto-loaded):

```json
{
  "token": "YOUR_APIKEY",
  "idses": "6797065fdfec41b50d649e64",
  "to": "34660558411",
  "template_name": "templateshipmentupdate",
  "variables": {
    "body": [
      "Emily",
      "OFFER105",
      "31/12/2025"
    ],
    "button": [
      {
        "index": 0,
        "payload": "promo2025"
      }
    ]
  }
}
```

Explicit media override (rare — only when user wants a different file):

```json
{
  "token": "YOUR_APIKEY",
  "idses": "6797065fdfec41b50d649e64",
  "to": "34660558411",
  "template_name": "templateshipmentupdate",
  "variables": {
    "header": "https://example.com/override-banner.jpg",
    "body": [
      "Emily",
      "OFFER105",
      "31/12/2025"
    ]
  }
}
```

Notes:

- Dispatch is now SYNCHRONOUS: the handler POSTs directly to https://graph.facebook.com/v20.0/{phone_number_id}/messages using the session's accestoken, and waits for Meta's response before replying. On success the response includes 'wamid' (Meta's message id) and the full 'meta_response'; on failure it includes 'meta_error'.
- Prefer the simplified 'variables' field over 'components'. The server reads the template's BODY/HEADER/BUTTONS metadata and auto-builds the correct Meta components array — you only need to supply raw values.
- Common Meta error causes (132xxx): (1) wrong number of parameters vs template definition, (2) passing text for a media header or vice versa, (3) URL button payload length/format not matching the approved template, (4) template language code mismatch.

### whatsapp_send_message

`POST https://api.datalyse.io/api/1.0/sendwhatsapp/sendmsg.json`

Send a free-form WhatsApp text message from one of the company's WhatsApp Business numbers to a single recipient. IMPORTANT: WhatsApp only allows free-form messages when the recipient has messaged the business within the last 24 hours (the 'customer service window'). If that window is closed, Meta will reject the message and you must instead use /api/1.0/sendwhatsapp/sendmsgtemplate.json with an approved template. Before calling this, pick a valid 'idses' (session _id) from /api/1.0/sendwhatsapp/getsessionsandtemplates.json — that tells you which WhatsApp number sends the message. Never invent text content; use exactly what the user asked to send.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| idses | string | yes | WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the message. Obtain from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required. |  |
| to | string | yes | Recipient phone number in full international format, digits only, no '+' sign or spaces (e.g. 34600000000). Required. | 34682288834 |
| text | string | yes | UTF-8 body of the WhatsApp message. Supports WhatsApp's basic markdown (*bold*, _italic_, ~strike~, ```mono```). Required. | hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendwhatsapp/sendmsg.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","idses":"","to":"34682288834","text":"hello world"}'
```

### whatsapp_send_file

`POST https://api.datalyse.io/api/1.0/sendwhatsapp/sendfile.json`

Send a media or document file (image, video, audio, PDF, spreadsheet, etc.) via WhatsApp to a single recipient, from one of the company's WhatsApp Business numbers. The file MUST already be hosted on a public HTTPS URL that Meta can download (no auth, no signed-url with short TTL). Same 24-hour free-form window rule as sendmsg.json: if the recipient has not written to the business in the last 24h, use sendmsgtemplate.json instead. Meta auto-detects the media type from the URL's Content-Type, so make sure the server returns the correct MIME. Optionally provide a 'filename' (mandatory for documents if you want the recipient to see a proper name) and a 'caption' that will display under images and videos.

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token of the company. Required. | YOUR_APIKEY |
| idses | string | yes | WhatsApp session _id (24-char Mongo ObjectId) identifying which WhatsApp Business number sends the file. Obtain from /api/1.0/sendwhatsapp/getsessionsandtemplates.json. Required. |  |
| to | string | yes | Recipient phone number in full international format, digits only, no '+' sign or spaces (e.g. 34600000000). Required. | 34682288834 |
| file_url | string | yes | Publicly reachable HTTPS URL of the file to send. Meta will fetch it; the host must serve the file without authentication and with the correct Content-Type header. Required. |  |
| filename | string | no | Display filename (including extension) shown to the recipient — especially important for PDFs and documents. Optional for images/videos. |  |
| caption | string | no | Optional caption text that appears under the media (images/videos only; ignored for audio and most document types). |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/sendwhatsapp/sendfile.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","idses":"","to":"34682288834","file_url":""}'
```

## Tasks

### get_tasks

`POST https://api.datalyse.io/api/1.0/tasks/get.json`

Get a list of tasks. Each result includes 'datestartunixutc' and 'dateendunixutc': start/end date+time as unix timestamps in SECONDS, timezone UTC (example: 1789041600 = 2026-09-10T12:00:00Z), plus the legacy date/time/dateEND/timeEND strings (also UTC).

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| var_status | string | no | Show only results with this status (optional) |  |
| var_agentfilter | string | no | Show only results for this agent ID (optional) |  |
| search_value | string | no | Text to search for (optional) |  |
| datefrom | string | no | Start date for filtering results (optional, format: YYYY-MM-DD) |  |
| dateto | string | no | End date for filtering results (optional, format: YYYY-MM-DD) |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tasks/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### edit_task

`POST https://api.datalyse.io/api/1.0/tasks/edit.json`

Edit a task

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| task_id | string | yes | ID of the task to edit |  |
| subject | string | no | Task subject (optional) |  |
| text | string | no | Task description (optional) |  |
| datestartunixutc | string | no | Task start date and time in ONE field: unix timestamp in SECONDS, not milliseconds. The timezone MUST be UTC (optional, recommended; example: 1789041600 = 2026-09-10T12:00:00Z). Convert the user's local time to UTC before sending. Replaces the legacy date+time pair. | 1789041600 |
| dateendunixutc | string | no | Task end date and time in ONE field: unix timestamp in SECONDS, not milliseconds. The timezone MUST be UTC (optional, recommended; example: 1789043400 = end 30 min after start). Convert the user's local time to UTC before sending. Replaces the legacy dateEND+timeEND pair. | 1789043400 |
| date | string | no | Legacy: task start date YYYY-MM-DD in UTC (optional; prefer datestartunixutc) |  |
| time | string | no | Legacy: task start time HH:MM in UTC (optional; prefer datestartunixutc) |  |
| dateEND | string | no | Legacy: task end date YYYY-MM-DD in UTC (optional; prefer dateendunixutc) |  |
| timeEND | string | no | Legacy: task end time HH:MM in UTC (optional; prefer dateendunixutc) |  |
| status | string | no | Status ID (optional) |  |
| agent_id | string | no | Agent ID or "unassigned" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tasks/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","task_id":"","datestartunixutc":"1789041600","dateendunixutc":"1789043400"}'
```

### delete_task

`POST https://api.datalyse.io/api/1.0/tasks/delete.json`

Delete a task

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| task_id | string | yes | ID of the task to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tasks/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","task_id":""}'
```

### add_note_to_task

`POST https://api.datalyse.io/api/1.0/tasks/addnote.json`

Add a note to a task

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| task_id | string | yes | ID of the task |  |
| text | string | yes | Text of the note | Hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tasks/addnote.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","task_id":"","text":"Hello world"}'
```

### get_task_activity

`POST https://api.datalyse.io/api/1.0/tasks/getactivity.json`

Get activity/timeline for a task

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| task_id | string | yes | ID of the task |  |
| type | string | no | Filter by activity type (optional) |  |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tasks/getactivity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","task_id":"","var_resultspage":"20","var_page":"1"}'
```

## Tickets

### create_ticket

`POST https://api.datalyse.io/api/1.0/tickets/create.json`

Create a new ticket

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| agent_id | string | no | Set to "unassigned" to assign this ticket to all agents, or provide a specific agent_id (optional) | unassigned |
| lead_id | string | yes | ID of the contact or company |  |
| ticketname | string | yes | Name for the ticket | Name for the ticket |
| ticketdescription | string | yes | Description for the ticket | Description for the ticket |
| status | string | yes | Status ID | 0 |
| pipeline | string | no | Pipeline ID (optional) |  |
| ticketvisiblecabinet | string | no | Visible in client cabinet (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/create.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","agent_id":"unassigned","lead_id":"","ticketname":"Name for the ticket","ticketdescription":"Description for the ticket","status":"0"}'
```

### get_tickets

`POST https://api.datalyse.io/api/1.0/tickets/get.json`

Get a list of tickets

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |
| var_status | string | no | Show only results with this status (optional) |  |
| var_agentfilter | string | no | Show only results for this agent ID (optional) |  |
| search_value | string | no | Text to search for (optional) |  |
| datefrom | string | no | Start date for filtering results (optional, format: YYYY-MM-DD) |  |
| dateto | string | no | End date for filtering results (optional, format: YYYY-MM-DD) |  |
| timezone | string | no | Timezone for date filtering (optional, example: Europe/Madrid) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/get.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","var_resultspage":"20","var_page":"1"}'
```

### edit_ticket

`POST https://api.datalyse.io/api/1.0/tickets/edit.json`

Edit a ticket

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| ticket_id | string | yes | ID of the ticket to edit |  |
| ticketname | string | no | Name for the ticket (optional) |  |
| ticketdescription | string | no | Description for the ticket (optional) |  |
| status | string | no | Status ID (optional) |  |
| pipeline | string | no | Pipeline ID (optional) |  |
| agent_id | string | no | Agent ID or "unassigned" (optional) |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/edit.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","ticket_id":""}'
```

### delete_ticket

`POST https://api.datalyse.io/api/1.0/tickets/delete.json`

Delete a ticket

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| ticket_id | string | yes | ID of the ticket to delete |  |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/delete.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","ticket_id":""}'
```

### add_note_to_ticket

`POST https://api.datalyse.io/api/1.0/tickets/addnote.json`

Add a note to a ticket

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| ticket_id | string | yes | ID of the ticket |  |
| text | string | yes | Text of the note | Hello world |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/addnote.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","ticket_id":"","text":"Hello world"}'
```

### get_ticket_activity

`POST https://api.datalyse.io/api/1.0/tickets/getactivity.json`

Get activity/timeline for a ticket

| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| token | string | yes | API access token | YOUR_APIKEY |
| ticket_id | string | yes | ID of the ticket |  |
| type | string | no | Filter by activity type (optional) |  |
| var_resultspage | string | yes | Maximum number of results to display | 20 |
| var_page | string | yes | Page number | 1 |

Example:

```bash
curl -X POST 'https://api.datalyse.io/api/1.0/tickets/getactivity.json' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_APIKEY","ticket_id":"","var_resultspage":"20","var_page":"1"}'
```