Lead Pool API (English)

POST /campaign-leads — request and response examples (English).

# MyVoipCRM External API — Lead Pool

**Endpoints:**
- `POST /api/external/v1/campaign-leads` — submit a lead
- `GET /api/external/v1/campaign-leads` — list leads and poll status updates
- `GET /api/external/v1/campaign-leads/{id}` — single lead with current status
- `PATCH /api/external/v1/campaign-leads/{id}/status` — optional; push status from your side

**Authentication:** `X-Api-Key` header (see general documentation for API key and IP allowlist)  
**Türkçe:** [lead-havuzu-entegrasyon.pdf](lead-havuzu-entegrasyon.pdf) · `/gelistirici/lead-havuzu-entegrasyon`

---

## Status flow (who owns what)

| Direction | Who | How |
|-----------|-----|-----|
| **Submit lead** | Your system → MyVoipCRM | `POST /campaign-leads` (do **not** send `status` unless you want an initial value; default is `0` New) |
| **Process lead** | MyVoipCRM CRM users | Agents work the lead in CRM and update **lead workflow status** (`status` 0–10) |
| **Receive status** | Your system ← MyVoipCRM | Poll `GET /campaign-leads` with `updatedFrom` / `updatedTo` (recommended every few minutes) |

`status` is the **workflow state** (Processing, Accepted, Paid, …).  
`leadPoolStatus` is **record validity** (valid phone / invalid phone / duplicate) — separate from workflow.

---

## Request (POST)

```json
{
  "fullName": "Ahmet Yilmaz",
  "phoneNumber1": "5321234567",
  "dialCode1": "+90",
  "countryCode1": "tr",
  "email": "[email protected]",
  "leadSource": "Web form",
  "externalId": "form-8842",
  "leadPriority": 2,
  "tags": ["hot"],
  "commercialDescription": "Requested a demo",
  "expectedRevenue": 1500,
  "offerId": "OFFER-8842",
  "offerName": "Premium Package Offer",
  "sub1": "campaign-42",
  "sub2": "landing-A",
  "sub3": "google",
  "sub4": "click-xyz",
  "payout": 25.50,
  "age": 34,
  "gender": "female",
  "region": "Istanbul",
  "status": 1,
  "customFields": {
    "budget": 150000,
    "interest": "Residential",
    "gdpr_consent": true,
    "meeting_date": "2026-10-05"
  }
}
```

| Field | Required | Notes |
|-------|----------|-------|
| `fullName` | Yes | |
| `phoneNumber1` | No | National number **without** country code. Invalid/missing → `leadPoolStatus: 1` |
| `dialCode1`, `countryCode1` | No | Country code separately (e.g. `+90`). Default `+90` / `tr` |
| `email`, `leadSource`, `externalId` | No | `leadSource`: webmaster ID; `externalId`: your order ID (**string**; numeric values are also accepted, e.g. `12345` → `"12345"`) |
| `leadPriority` | No | 1 low, 2 medium, 3 high |
| `tags`, `commercialDescription`, `expectedRevenue` | No | |
| `offerId`, `offerName` | No | External offer info (string; not linked to CRM `/biddings`) |
| `sub1`, `sub2`, `sub3`, `sub4` | No | Affiliate / webmaster tracking fields (max 256 chars each) |
| `payout` | No | Payment amount for the lead (decimal, ≥ 0) |
| `age` | No | Client age (0–150) |
| `gender` | No | Client gender (free text, max 64 chars, e.g. `male`, `female`, `M`, `F`) |
| `region` | No | Client region / city (max 256 chars) |
| `status` | No | **Usually omit.** Initial workflow status 0–10 (default: 0). CRM updates status after processing. |

### `offerId` and `offerName`

| Field | Direction | Notes |
|-------|-----------|-------|
| `offerId` | Request / Response | Optional. External offer identifier (string, max 256 characters) |
| `offerName` | Request / Response | Optional. External offer name (string, max 256 characters) |

These fields are stored on the lead only; they are **not** linked to the CRM bidding module (`/biddings`).

### Tracking fields (`sub1`–`sub4`, `payout`, demographics)

| Field | Direction | Notes |
|-------|-----------|-------|
| `sub1`–`sub4` | Request / Response | Optional affiliate / webmaster parameters (max 256 chars each). Returned on GET list/single lead. |
| `payout` | Request / Response | Optional payment amount for the lead (decimal, ≥ 0). Returned when polling status. |
| `age` | Request / Response | Optional client age (0–150). |
| `gender` | Request / Response | Optional client gender (free text). |
| `region` | Request / Response | Optional client region / city. |

When the same `externalId` is POSTed again, these fields are updated together with other lead data.

### `customFields` — Lead custom fields

Fields defined in CRM under **Lead campaigns › Lead custom fields** are sent by their **key** (`fieldKey`), shown for each field on that screen. Keys are case-insensitive.

| Field type | Value to send |
|------------|---------------|
| Text, Long text, Phone | String (numbers are accepted) |
| Email | String containing `@` |
| Number | Number or numeric string (`150000`, `"1250.5"`) |
| Date / Date-time | `yyyy-MM-dd` or ISO 8601 (`2026-10-05T14:30:00Z`); no offset means UTC |
| Select | Option value or its label; values not in the list are rejected |
| Checkbox | `true` / `false` (`1`/`0`, `"yes"`/`"no"` also accepted) |

- If `customFields` is omitted, custom fields are left untouched.
- For a **new lead**, fields marked required in CRM must be filled, otherwise `400` / `VALIDATION_FAILED`.
- On **update** (same `externalId`) only the fields you send change; `null` or an empty string clears that field. Required fields cannot be cleared.
- An unknown key rejects the request with `400` / `VALIDATION_FAILED`.
- Responses and status polling return filled fields in `customFields` as `fieldKey → value` (number, `yyyy-MM-dd`, ISO date-time, `true/false` or string).

### `status` — Lead workflow status

| Value | Description |
|------:|-------------|
| `0` | New (default) |
| `1` | Processing |
| `2` | Accepted |
| `3` | Cancelled |
| `4` | Sent to |
| `5` | Waiting for payment |
| `6` | Paid |
| `7` | Transfer |
| `8` | Return |
| `9` | Double |
| `10` | Spam/Error |

The response includes `statusDisplayName`. **To update status only (optional):** `PATCH /campaign-leads/{id}/status` — body: `{ "status": 2 }`. Most integrations should **poll GET** instead of pushing status.

`leadPoolStatus` (0 valid, 1 invalid phone, 2 duplicate) reflects record **validity**; `status` is the workflow state maintained in CRM.

### `externalId`

| Case | Result |
|------|--------|
| New `externalId` | New record |
| POST again with same `externalId` | Existing record updated (`wasUpdated: true`) |
| No `externalId` | Each request creates a new record; double-submit may create duplicates |

Use a unique `externalId` (submission ID, UUID) for form submissions.

### Phone

- `phoneNumber1` is optional; invalid/missing numbers do not reject the request → `leadPoolStatus: 1`.
- Even when invalid, the submitted value is stored in `data.phone`.
- Valid TR example: `5321234567` + `dialCode1: "+90"` → `phone: "905321234567"`.
- Invalid example: `90555555` → record is created, `leadPoolStatus: 1`, `isValidLead: false`.

**Minimum request example**

```json
{
  "fullName": "Mehmet Kaya",
  "phoneNumber1": "5329876543",
  "externalId": "form-9001"
}
```

---

## Response

```json
{
  "success": true,
  "message": "Lead added to pool successfully.",
  "data": {
    "id": 12045,
    "fullName": "Ahmet Yilmaz",
    "phone": "905321234567",
    "email": "[email protected]",
    "leadSource": "Web form",
    "externalId": "form-8842",
    "leadPriority": 2,
    "tags": ["hot"],
    "commercialDescription": "Requested a demo",
    "expectedRevenue": 1500,
    "offerId": "OFFER-8842",
    "offerName": "Premium Package Offer",
    "sub1": "campaign-42",
    "sub2": "landing-A",
    "sub3": "google",
    "sub4": "click-xyz",
    "payout": 25.50,
    "age": 34,
    "gender": "female",
    "region": "Istanbul",
    "status": 1,
    "statusDisplayName": "Processing",
    "createdAt": "2026-06-29T19:46:29Z",
    "updatedAt": "2026-07-06T10:15:00Z",
    "wasUpdated": false,
    "customerId": 501,
    "customerWasCreated": true,
    "customerWasLinked": true,
    "leadPoolStatus": 0,
    "leadPoolStatusDisplay": "Geçerli",
    "isValidLead": true,
    "customFields": {
      "budget": 150000,
      "interest": "Residential",
      "gdpr_consent": true,
      "meeting_date": "2026-10-05"
    }
  }
}
```

| Field | Description |
|-------|-------------|
| `id` | Created lead ID |
| `phone` | Stored phone (E.164 when valid) |
| `wasUpdated` | `true` → updated via same `externalId` |
| `leadPoolStatus` / `leadPoolStatusDisplay` | Record status (see below). `leadPoolStatusDisplay` is returned in Turkish from the API. |
| `isValidLead` | `true` → valid lead |
| `customerId` | Linked/created customer ID when phone is valid (`null` otherwise) |
| `customerWasCreated` / `customerWasLinked` | Customer create/link flags |
| `offerId` / `offerName` | External offer id and name (may be `null`) |
| `sub1`–`sub4` | Affiliate / webmaster tracking values |
| `payout` | Payment amount (may be `null`) |
| `age`, `gender`, `region` | Client demographics when provided |
| `status` / `statusDisplayName` | Lead workflow status (see below) |
| `updatedAt` | Last modification time (UTC); use for polling |

On update, `message` is: `"Lead pool record updated successfully."`

---

## Poll status updates (GET)

List leads submitted via External API and read their **current** workflow status.

```
GET /api/external/v1/campaign-leads?updatedFrom=2026-07-06T09:00:00Z&updatedTo=2026-07-06T12:00:00Z&page=1&pageSize=50
```

| Query | Required | Notes |
|-------|----------|-------|
| `page` | No | Default `1` |
| `pageSize` | No | Default `20`, max `100` |
| `externalId` | No | Exact match on a single submission / order id |
| `externalIds` | No | Read statuses of **several orders in one request**. Repeat the param (`externalIds=a&externalIds=b`) or send comma-separated (`externalIds=a,b,c`). Max `100` ids per request |
| `status` | No | Filter by workflow status `0`–`10` |
| `createdFrom`, `createdTo` | No | ISO 8601 UTC; filter by lead creation time |
| `updatedFrom`, `updatedTo` | No | ISO 8601 UTC; filter by last change — **use for polling** |

All filters are optional and combinable. To read statuses **by order id instead of by date**, just send `externalId` / `externalIds` without any date filter.

**Batch status lookup by order (no date filter):**

```
GET /api/external/v1/campaign-leads?externalIds=order-1001,order-1002,order-1003&pageSize=100
```

`externalId` and `externalIds` can be combined; their values are merged and de-duplicated. When you request more ids than fit in one page, increase `pageSize` (max `100`) or page through the results.

**Recommended polling:** every 5–15 minutes, call with `updatedFrom` = timestamp of your last successful poll. Max date range per request: **90 days**.

**Example response**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 12045,
        "externalId": "form-8842",
        "fullName": "Ahmet Yilmaz",
        "status": 2,
        "statusDisplayName": "Accepted",
        "updatedAt": "2026-07-06T10:15:00Z",
        "leadPoolStatus": 0,
        "isValidLead": true
      }
    ],
    "currentPage": 1,
    "pageSize": 50,
    "totalCount": 1,
    "totalPages": 1
  }
}
```

**Single lead:** `GET /api/external/v1/campaign-leads/{id}`

---

**Invalid phone response example**

```json
{
  "success": true,
  "data": {
    "id": 12046,
    "fullName": "Ahmet Yilmaz",
    "phone": "90555555",
    "leadPoolStatus": 1,
    "leadPoolStatusDisplay": "Geçersiz telefon",
    "isValidLead": false,
    "customerId": null
  }
}
```

### Customer

Runs only with a **valid phone** (`leadPoolStatus: 0`): if a customer with the same phone (primary or secondary) or, failing that, the same email already exists, no new customer is created; the lead is linked to the existing one. The name is not used for matching.

---

## `leadPoolStatus`

| Value | Meaning |
|------:|---------|
| `0` | Valid |
| `1` | Invalid phone |
| `2` | Duplicate resubmit (5 min, same name+phone+email) |

If the pool already has the same `fullName` + `phone` + `email` within the last 5 minutes, the new record gets status `2`. A resubmit with the same `externalId` is an update, not a duplicate.

---

## HTTP status codes

| Code | Meaning |
|------|---------|
| `200` | Success (record created or updated) |
| `400` | Validation error |
| `401` | Invalid API key |
| `403` | IP not allowed |
| `409` | `externalId` conflict |
| `429` | Rate limit exceeded |
| `500` | Server error |

---

## Error codes

| `code` | HTTP | When |
|--------|------|------|
| `FULL_NAME_REQUIRED` | 400 | `fullName` is empty |
| `VALIDATION_FAILED` | 400 | Invalid field (email length, tag count, `leadPriority`, negative `expectedRevenue`, etc.) |
| `INVALID_API_KEY` | 401 | Missing or invalid `X-Api-Key` |
| `IP_NOT_ALLOWED` | 403 | Server IP not on CRM allowlist |
| `EXTERNAL_ID_CONFLICT` | 409 | Concurrent conflict on same `externalId` |
| `RATE_LIMIT_EXCEEDED` | 429 | Rate limit |
| `UNEXPECTED_ERROR` | 500 | Unexpected server error |

**Error response format**

```json
{
  "success": false,
  "message": "FullName is required.",
  "code": "FULL_NAME_REQUIRED"
}
```

---

## cURL

**Submit lead**

```bash
curl -X POST "https://externalapi.myvoipcrm.com/api/external/v1/campaign-leads" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: crm_xxxxx" \
  -d "{\"fullName\":\"Ahmet Yilmaz\",\"phoneNumber1\":\"5321234567\",\"dialCode1\":\"+90\",\"externalId\":\"form-8842\"}"
```

**Poll status updates**

```bash
curl -G "https://externalapi.myvoipcrm.com/api/external/v1/campaign-leads" \
  -H "X-Api-Key: crm_xxxxx" \
  --data-urlencode "updatedFrom=2026-07-06T09:00:00Z" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=50"
```