Lead Pool API
POST /campaign-leads — request and response examples.
# 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"
```