API reference

Leads

6 endpoints

Inbound enquiries and the pipeline they move through. stage advances via PATCH /api/v1/leads/{id}/transition rather than a plain update, because the move is recorded with its actor and, for a loss, its reason.

POST /api/v1/leads/{id}/convert is the terminal step: it mints a Customer and a Trip from the lead in one transaction and answers with all three.

List leads

GET/api/v1/leads

Needs a key with the full scope.

Most recently touched first (updated_at descending).

Parameters

Query

qstring
Matches name, email or phone.
stagestring
sourcestring
assigned_to_iduuid
scopeenum
A named slice, applied on top of the other filters. mine is relative to the key's principal, which for an unbound key is the account owner.
one ofopenclosedstalemine
limitintegerdefault 25
Rows per page.
cursorstring
Opaque; take it from the previous response's page.next_cursor.

Response · 200

dataobject[]required
Show fieldsHide fields
- iduuid
- namestringnullable
- emailstringnullable
- phonestringnullable
- stagestring
- scoreintegernullable
- sourcestringnullable
- estimated_valuestringnullable
  Decimal as a string, to avoid float rounding.
- currencystringnullable
- destinationsstring[]
- party_sizeintegernullable
- target_departure_ondatenullable
- target_return_ondatenullable
- assigned_toobjectnullable
  A seat on the account, as referenced from other records.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
- customer_iduuidnullable
  Set once the lead converts.
- trip_iduuidnullable
- updated_atdate-time
pageobjectrequired
The cursor for the list beside it. Re-send the same request with ?cursor=<next_cursor> while has_more is true. next_cursor is null on the last page.
Show fieldsHide fields
- next_cursorstringrequirednullable
- has_morebooleanrequired
- limitintegerrequired

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
429Rate limit exceeded

curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/leads' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.get(
    "https://YOUR-CELL.lydira.com/api/v1/leads",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": [
    {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com",
      "phone": "+90 532 111 22 33",
      "stage": "inbox",
      "score": 1,
      "source": "website_form",
      "estimated_value": "12500.00",
      "currency": "EUR",
      "destinations": [
        "Cappadocia",
        "Istanbul"
      ],
      "party_size": 1,
      "target_departure_on": "2026-03-14",
      "target_return_on": "2026-03-14",
      "assigned_to": {
        "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com"
      },
      "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "updated_at": "2026-03-14T09:30:00Z"
    }
  ],
  "page": {
    "next_cursor": "MjAyNi0wMy0xNFQwOTozMDowMC4wMDAwMDBafDk0MQ",
    "has_more": true,
    "limit": 25
  }
}

Capture a lead

POST/api/v1/leads

Needs a key with the full scope.

Defaults fill in what you leave out: stage starts at inbox, assigned_to_id and the creator both become the key's principal, and company_id falls back to that principal's home company.

A lead pushed from another system should go through POST /api/v1/imports/leads instead, which carries your external_id and upserts on it.

Parameters

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Body

leadobjectrequired
Show fieldsHide fields
- namestring
- emailemail
- phonestring
- sourcestring
- party_sizeinteger
- estimated_valuestring
- currencystring
- target_departure_ondate
- target_return_ondate
- notesstring
- assigned_to_iduuid
- company_iduuid
- destinationsstring[]
- preferencesobject

Response · 201

dataobject
Show fieldsHide fields
- iduuid
- namestringnullable
- emailstringnullable
- phonestringnullable
- stagestring
- scoreintegernullable
- sourcestringnullable
- estimated_valuestringnullable
  Decimal as a string, to avoid float rounding.
- currencystringnullable
- destinationsstring[]
- party_sizeintegernullable
- target_departure_ondatenullable
- target_return_ondatenullable
- assigned_toobjectnullable
  A seat on the account, as referenced from other records.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
- customer_iduuidnullable
  Set once the lead converts.
- trip_iduuidnullable
- updated_atdate-time
- notesstringnullable
- preferencesobject
- qualified_atdate-timenullable
- won_atdate-timenullable
- lost_atdate-timenullable
- lost_reasonstringnullable
- scored_atdate-timenullable
- utmobject
  Only the keys that were captured.
  Show fieldsHide fields
  - sourcestring
  - mediumstring
  - campaignstring
  - termstring
  - contentstring
- created_atdate-time

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
422The request was understood but the record could not be written. details maps each rejected attribute to its reasons, so a client can put the message next to the field that caused it.
429Rate limit exceeded

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/leads' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "lead": {
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "source": "website_form",
    "party_size": 1,
    "estimated_value": "12500.00"
  }
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "lead": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com",
        "phone": "+90 532 111 22 33",
        "source": "website_form",
        "party_size": 1,
        "estimated_value": "12500.00"
      }
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/leads",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "lead": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com",
        "phone": "+90 532 111 22 33",
        "source": "website_form",
        "party_size": 1,
        "estimated_value": "12500.00"
      }
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  lead: {
    name: "Ayşe Yılmaz",
    email: "ayse@example.com",
    phone: "+90 532 111 22 33",
    source: "website_form",
    party_size: 1,
    estimated_value: "12500.00"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "lead" => [
            "name" => "Ayşe Yılmaz",
            "email" => "ayse@example.com",
            "phone" => "+90 532 111 22 33",
            "source" => "website_form",
            "party_size" => 1,
            "estimated_value" => "12500.00",
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

201

{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "stage": "inbox",
    "score": 1,
    "source": "website_form",
    "estimated_value": "12500.00",
    "currency": "EUR",
    "destinations": [
      "Cappadocia",
      "Istanbul"
    ],
    "party_size": 1,
    "target_departure_on": "2026-03-14",
    "target_return_on": "2026-03-14",
    "assigned_to": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "updated_at": "2026-03-14T09:30:00Z",
    "notes": "Prefers boutique hotels, no early flights.",
    "preferences": {},
    "qualified_at": "2026-03-14T09:30:00Z",
    "won_at": "2026-03-14T09:30:00Z",
    "lost_at": "2026-03-14T09:30:00Z",
    "lost_reason": "string",
    "scored_at": "2026-03-14T09:30:00Z",
    "utm": {
      "source": "website_form",
      "medium": "string",
      "campaign": "string",
      "term": "string",
      "content": "string"
    },
    "created_at": "2026-03-14T09:30:00Z"
  }
}

Read a lead

GET/api/v1/leads/{id}

Needs a key with the full scope.

Parameters

Path

iduuidrequired

Response · 200

dataobject
Show fieldsHide fields
- iduuid
- namestringnullable
- emailstringnullable
- phonestringnullable
- stagestring
- scoreintegernullable
- sourcestringnullable
- estimated_valuestringnullable
  Decimal as a string, to avoid float rounding.
- currencystringnullable
- destinationsstring[]
- party_sizeintegernullable
- target_departure_ondatenullable
- target_return_ondatenullable
- assigned_toobjectnullable
  A seat on the account, as referenced from other records.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
- customer_iduuidnullable
  Set once the lead converts.
- trip_iduuidnullable
- updated_atdate-time
- notesstringnullable
- preferencesobject
- qualified_atdate-timenullable
- won_atdate-timenullable
- lost_atdate-timenullable
- lost_reasonstringnullable
- scored_atdate-timenullable
- utmobject
  Only the keys that were captured.
  Show fieldsHide fields
  - sourcestring
  - mediumstring
  - campaignstring
  - termstring
  - contentstring
- created_atdate-time

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
404Resource not found
429Rate limit exceeded

curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.get(
    "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "stage": "inbox",
    "score": 1,
    "source": "website_form",
    "estimated_value": "12500.00",
    "currency": "EUR",
    "destinations": [
      "Cappadocia",
      "Istanbul"
    ],
    "party_size": 1,
    "target_departure_on": "2026-03-14",
    "target_return_on": "2026-03-14",
    "assigned_to": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "updated_at": "2026-03-14T09:30:00Z",
    "notes": "Prefers boutique hotels, no early flights.",
    "preferences": {},
    "qualified_at": "2026-03-14T09:30:00Z",
    "won_at": "2026-03-14T09:30:00Z",
    "lost_at": "2026-03-14T09:30:00Z",
    "lost_reason": "string",
    "scored_at": "2026-03-14T09:30:00Z",
    "utm": {
      "source": "website_form",
      "medium": "string",
      "campaign": "string",
      "term": "string",
      "content": "string"
    },
    "created_at": "2026-03-14T09:30:00Z"
  }
}

Update a lead

PATCH/api/v1/leads/{id}

Needs a key with the full scope.

Partial; PUT is routed to the same action. stage is deliberately not writable here. Move it with PATCH /api/v1/leads/{id}/transition, which records the actor and the reason.

Parameters

Path

iduuidrequired

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Body

leadobjectrequired
Show fieldsHide fields
- namestring
- emailemail
- phonestring
- sourcestring
- party_sizeinteger
- estimated_valuestring
- currencystring
- target_departure_ondate
- target_return_ondate
- notesstring
- assigned_to_iduuid
- company_iduuid
- destinationsstring[]
- preferencesobject

Response · 200

dataobject
Show fieldsHide fields
- iduuid
- namestringnullable
- emailstringnullable
- phonestringnullable
- stagestring
- scoreintegernullable
- sourcestringnullable
- estimated_valuestringnullable
  Decimal as a string, to avoid float rounding.
- currencystringnullable
- destinationsstring[]
- party_sizeintegernullable
- target_departure_ondatenullable
- target_return_ondatenullable
- assigned_toobjectnullable
  A seat on the account, as referenced from other records.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
- customer_iduuidnullable
  Set once the lead converts.
- trip_iduuidnullable
- updated_atdate-time
- notesstringnullable
- preferencesobject
- qualified_atdate-timenullable
- won_atdate-timenullable
- lost_atdate-timenullable
- lost_reasonstringnullable
- scored_atdate-timenullable
- utmobject
  Only the keys that were captured.
  Show fieldsHide fields
  - sourcestring
  - mediumstring
  - campaignstring
  - termstring
  - contentstring
- created_atdate-time

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
404Resource not found
422The request was understood but the record could not be written. details maps each rejected attribute to its reasons, so a client can put the message next to the field that caused it.
429Rate limit exceeded

curl -X PATCH 'https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "lead": {
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "source": "website_form",
    "party_size": 1,
    "estimated_value": "12500.00"
  }
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "lead": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com",
        "phone": "+90 532 111 22 33",
        "source": "website_form",
        "party_size": 1,
        "estimated_value": "12500.00"
      }
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.patch(
    "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "lead": {
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com",
        "phone": "+90 532 111 22 33",
        "source": "website_form",
        "party_size": 1,
        "estimated_value": "12500.00"
      }
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  lead: {
    name: "Ayşe Yılmaz",
    email: "ayse@example.com",
    phone: "+90 532 111 22 33",
    source: "website_form",
    party_size: 1,
    estimated_value: "12500.00"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "PATCH",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "lead" => [
            "name" => "Ayşe Yılmaz",
            "email" => "ayse@example.com",
            "phone" => "+90 532 111 22 33",
            "source" => "website_form",
            "party_size" => 1,
            "estimated_value" => "12500.00",
        ],
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "stage": "inbox",
    "score": 1,
    "source": "website_form",
    "estimated_value": "12500.00",
    "currency": "EUR",
    "destinations": [
      "Cappadocia",
      "Istanbul"
    ],
    "party_size": 1,
    "target_departure_on": "2026-03-14",
    "target_return_on": "2026-03-14",
    "assigned_to": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "updated_at": "2026-03-14T09:30:00Z",
    "notes": "Prefers boutique hotels, no early flights.",
    "preferences": {},
    "qualified_at": "2026-03-14T09:30:00Z",
    "won_at": "2026-03-14T09:30:00Z",
    "lost_at": "2026-03-14T09:30:00Z",
    "lost_reason": "string",
    "scored_at": "2026-03-14T09:30:00Z",
    "utm": {
      "source": "website_form",
      "medium": "string",
      "campaign": "string",
      "term": "string",
      "content": "string"
    },
    "created_at": "2026-03-14T09:30:00Z"
  }
}

Move a lead to another stage

PATCH/api/v1/leads/{id}/transition

Needs a key with the full scope.

The audited way to change stage. The move is stamped with the actor and, when the new stage is lost, with reason.

An unknown stage answers 422 invalid_stage. A move the pipeline does not allow answers 422 validation_failed.

Parameters

Path

iduuidrequired

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Body

new_stagestringrequired
A stage key. GET /api/v1/leads/{id} reports the current one.
reasonstring
Recorded on the lead. Meaningful when moving to lost.

Response · 200

dataobject
Show fieldsHide fields
- iduuid
- namestringnullable
- emailstringnullable
- phonestringnullable
- stagestring
- scoreintegernullable
- sourcestringnullable
- estimated_valuestringnullable
  Decimal as a string, to avoid float rounding.
- currencystringnullable
- destinationsstring[]
- party_sizeintegernullable
- target_departure_ondatenullable
- target_return_ondatenullable
- assigned_toobjectnullable
  A seat on the account, as referenced from other records.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
- customer_iduuidnullable
  Set once the lead converts.
- trip_iduuidnullable
- updated_atdate-time
- notesstringnullable
- preferencesobject
- qualified_atdate-timenullable
- won_atdate-timenullable
- lost_atdate-timenullable
- lost_reasonstringnullable
- scored_atdate-timenullable
- utmobject
  Only the keys that were captured.
  Show fieldsHide fields
  - sourcestring
  - mediumstring
  - campaignstring
  - termstring
  - contentstring
- created_atdate-time

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
404Resource not found
422Unknown or illegal stage
429Rate limit exceeded

curl -X PATCH 'https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/transition' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90' \
  -d '{
  "new_stage": "qualified",
  "reason": "Booked with another agency"
}'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/transition",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    body: JSON.stringify({
      "new_stage": "qualified",
      "reason": "Booked with another agency"
    }),
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.patch(
    "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/transition",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
    json={
      "new_stage": "qualified",
      "reason": "Booked with another agency"
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/transition")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"
request.body = JSON.generate({
  new_stage: "qualified",
  reason: "Booked with another agency"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/transition");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "PATCH",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Content-Type: application/json",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        "new_stage" => "qualified",
        "reason" => "Booked with another agency",
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "name": "Ayşe Yılmaz",
    "email": "ayse@example.com",
    "phone": "+90 532 111 22 33",
    "stage": "inbox",
    "score": 1,
    "source": "website_form",
    "estimated_value": "12500.00",
    "currency": "EUR",
    "destinations": [
      "Cappadocia",
      "Istanbul"
    ],
    "party_size": 1,
    "target_departure_on": "2026-03-14",
    "target_return_on": "2026-03-14",
    "assigned_to": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com"
    },
    "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "updated_at": "2026-03-14T09:30:00Z",
    "notes": "Prefers boutique hotels, no early flights.",
    "preferences": {},
    "qualified_at": "2026-03-14T09:30:00Z",
    "won_at": "2026-03-14T09:30:00Z",
    "lost_at": "2026-03-14T09:30:00Z",
    "lost_reason": "string",
    "scored_at": "2026-03-14T09:30:00Z",
    "utm": {
      "source": "website_form",
      "medium": "string",
      "campaign": "string",
      "term": "string",
      "content": "string"
    },
    "created_at": "2026-03-14T09:30:00Z"
  }
}

Convert a lead into a customer and a trip

POST/api/v1/leads/{id}/convert

Needs a key with the full scope.

One transaction: a Customer is created (or matched), a Trip is opened from the lead's destinations and dates, and the lead is linked to both. The response carries all three.

Not idempotent on its own. Converting an already-converted lead answers 422 conversion_failed; send an Idempotency-Key if your caller may retry.

Parameters

Path

iduuidrequired

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Response · 201

dataobject
Show fieldsHide fields
- leadobjectrequired
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - emailstringnullable
  - phonestringnullable
  - stagestring
  - scoreintegernullable
  - sourcestringnullable
  - estimated_valuestringnullable
    Decimal as a string, to avoid float rounding.
  - currencystringnullable
  - destinationsstring[]
  - party_sizeintegernullable
  - target_departure_ondatenullable
  - target_return_ondatenullable
  - assigned_toobjectnullable
    A seat on the account, as referenced from other records.
    Show fieldsHide fields
    iduuid
    namestringnullable
    emailstringnullable
  - customer_iduuidnullable
    Set once the lead converts.
  - trip_iduuidnullable
  - updated_atdate-time
  - notesstringnullable
  - preferencesobject
  - qualified_atdate-timenullable
  - won_atdate-timenullable
  - lost_atdate-timenullable
  - lost_reasonstringnullable
  - scored_atdate-timenullable
  - utmobject
    Only the keys that were captured.
    Show fieldsHide fields
    sourcestring
    mediumstring
    campaignstring
    termstring
    contentstring
  - created_atdate-time
- tripobjectrequired
  Show fieldsHide fields
  - iduuid
  - titlestring
  - statusstring
  - start_datedatenullable
- customerobjectrequired
  List shape. name, email and phone are personal data: a key whose role cannot read PII gets null, and a customer carrying a restricted tag has its name masked too.
  Show fieldsHide fields
  - iduuid
  - namestringnullable
  - customer_typestring
  - emailstringnullable
  - phonestringnullable
  - lifecycle_stagestringnullable
  - vip_tierstringnullable
  - activeboolean
  - tagsstring[]
  - company_iduuid

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
404Resource not found
422The lead could not be converted
429Rate limit exceeded

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/convert' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/convert",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/convert",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/convert")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/leads/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/convert");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

201

{
  "data": {
    "lead": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "email": "ayse@example.com",
      "phone": "+90 532 111 22 33",
      "stage": "inbox",
      "score": 1,
      "source": "website_form",
      "estimated_value": "12500.00",
      "currency": "EUR",
      "destinations": [
        "Cappadocia",
        "Istanbul"
      ],
      "party_size": 1,
      "target_departure_on": "2026-03-14",
      "target_return_on": "2026-03-14",
      "assigned_to": {
        "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
        "name": "Ayşe Yılmaz",
        "email": "ayse@example.com"
      },
      "customer_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "trip_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "updated_at": "2026-03-14T09:30:00Z",
      "notes": "Prefers boutique hotels, no early flights.",
      "preferences": {},
      "qualified_at": "2026-03-14T09:30:00Z",
      "won_at": "2026-03-14T09:30:00Z",
      "lost_at": "2026-03-14T09:30:00Z",
      "lost_reason": "string",
      "scored_at": "2026-03-14T09:30:00Z",
      "utm": {
        "source": "website_form",
        "medium": "string",
        "campaign": "string",
        "term": "string",
        "content": "string"
      },
      "created_at": "2026-03-14T09:30:00Z"
    },
    "trip": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "title": "Cappadocia, 4 nights",
      "status": "confirmed",
      "start_date": "2026-03-14"
    },
    "customer": {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "name": "Ayşe Yılmaz",
      "customer_type": "individual",
      "email": "ayse@example.com",
      "phone": "+90 532 111 22 33",
      "lifecycle_stage": "active",
      "vip_tier": "gold",
      "active": true,
      "tags": [
        "vip",
        "repeat"
      ],
      "company_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18"
    }
  }
}