API Reference Overview

Dokumen ini merangkum endpoint Public API v1 untuk leads. Semua request memakai header Authorization: Bearer <api_key> dan base URL berikut:

https://konektor.id

Contoh di halaman ini menampilkan field yang paling sering dipakai. Untuk referensi machine-readable dan artefak yang bisa di-import ke tool lain, gunakan link OpenAPI dan Postman di bagian akhir halaman.

Autentikasi & Scope API Key

Scope resmi yang didukung:

Scope	Akses
`leads.read`	`GET /api/v1/leads`, `GET /api/v1/leads/{identifier}`
`leads.write`	`POST /api/v1/leads`, `PATCH /api/v1/leads/{identifier}`, `POST /api/v1/leads/upsert`
`leads.delete`	`DELETE /api/v1/leads/{identifier}`
`leads.bulk`	`POST /api/v1/leads/bulk-upsert` dan kompatibel untuk upsert

API key akan ditolak jika tidak valid, sudah dicabut, sudah kedaluwarsa, tidak memiliki scope yang diperlukan, atau berasal dari IP di luar allowlist key tersebut.

Deprecation Scope Delete

Endpoint delete menerima scope lama leads.write hanya sampai 30 September 2026. Setelah itu, endpoint delete wajib leads.delete.

Saat fallback scope lama dipakai di masa transisi, backend mengirim header x-konektor-deprecation-warning dan Warning.

Endpoint Public API v1 Leads

Method	Path	Scope	Keterangan
`GET`	`/api/v1/leads`	`leads.read`	List leads dengan filter advanced dan pagination
`POST`	`/api/v1/leads`	`leads.write`	Create lead
`GET`	`/api/v1/leads/{identifier}`	`leads.read`	Detail lead
`PATCH`	`/api/v1/leads/{identifier}`	`leads.write`	Update lead
`DELETE`	`/api/v1/leads/{identifier}`	`leads.delete`	Soft delete lead
`POST`	`/api/v1/leads/upsert`	`leads.write` atau `leads.bulk`	Upsert lead by matcher
`POST`	`/api/v1/leads/bulk-upsert`	`leads.bulk`	Bulk upsert maksimal 100 item

Format `{identifier}`

{identifier} dapat berupa salah satu nilai berikut:

id
uniqueCode
externalRef
phone

Contoh:

/api/v1/leads/550e8400-e29b-41d4-a716-446655440000
/api/v1/leads/API_7F3A1B2C
/api/v1/leads/CRM-1024
/api/v1/leads/6281234567890

Saat memakai nomor telepon, gunakan format yang konsisten jika memungkinkan. Backend tetap mencoba menormalkan variasi format nomor yang umum.

List Leads `GET /api/v1/leads`

Endpoint ini mendukung filter, sorting, dan cursor pagination. Cursor pagination bersifat stabil dengan tie-breaker id.

Query yang tersedia:

Query	Keterangan
`status`	Single status atau CSV, misalnya `new,qualified`
`priority`	`low`, `medium`, `high`, `urgent`
`source`	`website`, `whatsapp`, `phone`, `email`, `referral`, `social`, `ads`, `event`, `other`
`adPlatform`	`meta`, `google`, `tiktok`, `linkedin`, `posthog`, `other`
`assignedTo`	UUID user yang menangani lead
`createdFrom`, `createdTo`	Batas waktu `createdAt` dalam format ISO 8601
`updatedFrom`, `updatedTo`	Batas waktu `updatedAt` dalam format ISO 8601
`sortBy`	`createdAt` atau `updatedAt`
`sortOrder`	`asc` atau `desc`
`cursor`	Token pagination keyset
`limit`	Maksimum `100`, default `50`
`page`	Mode legacy. Diabaikan jika `cursor` dikirim
`search`	Cari berdasarkan nama, email, phone, `uniqueCode`, atau `externalRef`

Contoh request:

curl -X GET "https://konektor.id/api/v1/leads?status=new,qualified&limit=2&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer <api_key>"

Contoh response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uniqueCode": "API_7F3A1B2C",
      "externalRef": "CRM-1024",
      "firstName": "Budi",
      "lastName": "Santoso",
      "email": "budi@example.com",
      "phone": "6281234567890",
      "status": "new",
      "priority": "high",
      "source": "website",
      "adPlatform": "meta",
      "assignedTo": null,
      "estimatedValue": 3500000,
      "actualValue": null,
      "notes": "Minta demo produk",
      "createdAt": "2026-03-06T02:15:30.000Z",
      "updatedAt": "2026-03-06T02:15:30.000Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 2,
    "total": 24,
    "totalPages": 12,
    "cursor": null,
    "nextCursor": "<opaque-cursor-token>"
  }
}

Saat memakai mode cursor, page dan totalPages bernilai null. Perlakukan nextCursor sebagai token opaque dan kirim kembali nilainya apa adanya ke request berikutnya.

Create Lead `POST /api/v1/leads`

Field wajib hanya firstName. Jika field berikut tidak dikirim, backend memakai default: status = new, priority = medium, source = other, dan uniqueCode akan dibuat otomatis.

Contoh request:

curl -X POST "https://konektor.id/api/v1/leads" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Budi",
    "lastName": "Santoso",
    "email": "budi@example.com",
    "phone": "6281234567890",
    "priority": "high",
    "source": "website",
    "adPlatform": "meta",
    "estimatedValue": 3500000,
    "externalRef": "CRM-1024",
    "notes": "Minta demo produk"
  }'

Contoh response:

{
  "success": true,
  "message": "Lead created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "lastName": "Santoso",
    "email": "budi@example.com",
    "phone": "6281234567890",
    "status": "new",
    "priority": "high",
    "source": "website",
    "adPlatform": "meta",
    "estimatedValue": 3500000,
    "actualValue": null,
    "notes": "Minta demo produk",
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T02:15:30.000Z",
    "deletedAt": null
  },
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "lastName": "Santoso",
    "email": "budi@example.com",
    "phone": "6281234567890",
    "status": "new",
    "priority": "high",
    "source": "website",
    "adPlatform": "meta",
    "estimatedValue": 3500000,
    "actualValue": null,
    "notes": "Minta demo produk",
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T02:15:30.000Z",
    "deletedAt": null
  }
}

Get Lead Detail `GET /api/v1/leads/{identifier}`

Endpoint ini mengembalikan satu lead berdasarkan id, uniqueCode, externalRef, atau phone.

Contoh request:

curl -X GET "https://konektor.id/api/v1/leads/CRM-1024" \
  -H "Authorization: Bearer <api_key>"

Contoh response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "lastName": "Santoso",
    "email": "budi@example.com",
    "phone": "6281234567890",
    "status": "new",
    "priority": "high",
    "source": "website",
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T02:15:30.000Z",
    "deletedAt": null
  }
}

Update Lead `PATCH /api/v1/leads/{identifier}`

Kirim hanya field yang ingin diubah. Untuk field nullable seperti lastName, phone, externalRef, notes, estimatedValue, dan actualValue, kirim null untuk mengosongkan nilainya.

Endpoint ini juga menerima value sebagai alias untuk actualValue. Response update menyertakan previousStatus dan alias value pada object lead.

Contoh request:

curl -X PATCH "https://konektor.id/api/v1/leads/CRM-1024" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified",
    "actualValue": 1500000,
    "notes": "Sudah dijadwalkan untuk demo"
  }'

Contoh response:

{
  "success": true,
  "message": "Lead updated successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "status": "qualified",
    "priority": "high",
    "source": "website",
    "actualValue": 1500000,
    "notes": "Sudah dijadwalkan untuk demo",
    "previousStatus": "new",
    "value": 1500000,
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T03:10:00.000Z",
    "deletedAt": null
  },
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "status": "qualified",
    "priority": "high",
    "source": "website",
    "actualValue": 1500000,
    "notes": "Sudah dijadwalkan untuk demo",
    "previousStatus": "new",
    "value": 1500000,
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T03:10:00.000Z",
    "deletedAt": null
  }
}

Jika payload valid tetapi tidak mengubah data apa pun, backend mengembalikan success: true, message: "No changes detected", dan object lead terbaru.

Upsert Lead `POST /api/v1/leads/upsert`

Body upsert wajib berisi match dan lead. Field match.by hanya menerima id, uniqueCode, phone, atau externalRef.

Jika lead ditemukan, backend mengembalikan action: "updated". Jika lead tidak ditemukan dan createIfMissing tidak di-set ke false, backend akan membuat lead baru dan mengembalikan action: "created".

Saat match.by adalah phone, uniqueCode, atau externalRef, backend akan memakai match.value sebagai nilai create jika field yang sama tidak dikirim di lead.

Contoh request:

curl -X POST "https://konektor.id/api/v1/leads/upsert" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "match": {
      "by": "phone",
      "value": "6281234567890"
    },
    "lead": {
      "firstName": "Budi",
      "status": "qualified",
      "priority": "high",
      "source": "whatsapp"
    },
    "createIfMissing": true
  }'

Contoh response:

{
  "success": true,
  "action": "updated",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "phone": "6281234567890",
    "status": "qualified",
    "priority": "high",
    "source": "whatsapp",
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T03:25:00.000Z",
    "deletedAt": null
  },
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_7F3A1B2C",
    "externalRef": "CRM-1024",
    "firstName": "Budi",
    "phone": "6281234567890",
    "status": "qualified",
    "priority": "high",
    "source": "whatsapp",
    "createdAt": "2026-03-06T02:15:30.000Z",
    "updatedAt": "2026-03-06T03:25:00.000Z",
    "deletedAt": null
  }
}

Bulk Upsert `POST /api/v1/leads/bulk-upsert`

Endpoint ini menerima items[] dengan maksimum 100 item. options.continueOnError default-nya true, sehingga item lain tetap diproses walaupun ada item yang gagal.

Contoh request:

curl -X POST "https://konektor.id/api/v1/leads/bulk-upsert" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "match": {
          "by": "externalRef",
          "value": "CRM-1024"
        },
        "lead": {
          "firstName": "Budi",
          "status": "qualified"
        }
      },
      {
        "match": {
          "by": "externalRef",
          "value": "CRM-2048"
        },
        "lead": {},
        "createIfMissing": false
      }
    ],
    "options": {
      "continueOnError": true
    }
  }'

Contoh response:

{
  "success": false,
  "processed": 2,
  "created": 0,
  "updated": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "match": {
        "by": "externalRef",
        "value": "CRM-1024"
      },
      "success": true,
      "action": "updated",
      "lead": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "uniqueCode": "API_7F3A1B2C",
        "externalRef": "CRM-1024",
        "firstName": "Budi",
        "status": "qualified",
        "createdAt": "2026-03-06T02:15:30.000Z",
        "updatedAt": "2026-03-06T03:25:00.000Z",
        "deletedAt": null
      }
    },
    {
      "index": 1,
      "match": {
        "by": "externalRef",
        "value": "CRM-2048"
      },
      "success": false,
      "error": {
        "statusCode": 404,
        "statusMessage": "Lead not found and createIfMissing is false"
      }
    }
  ]
}

Delete Lead `DELETE /api/v1/leads/{identifier}`

Endpoint ini melakukan soft delete. Response sukses hanya mengembalikan status dan pesan.

Contoh request:

curl -X DELETE "https://konektor.id/api/v1/leads/CRM-1024" \
  -H "Authorization: Bearer <api_key>"

Contoh response:

{
  "success": true,
  "message": "Lead deleted successfully"
}

Jika request masih memakai scope legacy leads.write dalam masa transisi, response sukses juga menyertakan header x-konektor-deprecation-warning.

Format Response & Error

Wrapper response yang dipakai backend:

List endpoint mengembalikan success, data, dan pagination.
Create, update, dan upsert mengembalikan success, object lead di data, dan alias lead.
Detail mengembalikan success dan data.
Delete mengembalikan success dan message.

Format error umum:

{
  "statusCode": 404,
  "statusMessage": "Lead not found"
}

Contoh error lain yang umum:

{
  "statusCode": 400,
  "statusMessage": "Invalid cursor format"
}

{
  "statusCode": 409,
  "statusMessage": "Lead with this externalRef already exists",
  "data": {
    "field": "externalRef"
  }
}

{
  "statusCode": 429,
  "statusMessage": "Daily lead limit reached"
}

Validation error body dapat menyertakan field data berisi detail per-field dari validator.

Keamanan Data

Field PII utama lead, seperti nama, email, dan phone, disimpan terenkripsi at-rest. Lookup nomor telepon juga mempertimbangkan normalisasi format umum agar request dengan variasi format nomor tetap bisa menemukan lead yang sama.

Limit & Quota Aktual

Create dan upsert-create tetap mematuhi daily lead quota workspace.
bulk-upsert menerima maksimal 100 item per request.
Limit transport atau runtime platform tetap dapat berlaku di luar quota bisnis di atas.

Artefak Kontrak

Artefak kontrak public tersedia di:

Butuh Bantuan Lebih Lanjut?

Tim kami siap membantu Anda memaksimalkan potensi tracking iklan dan atribusi bisnis Anda.

Email Supportsupport@konektor.id

YouTubeYouTube

Jadwalkan Sesi

Onboarding Demo Meeting Technical Support