> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simz.com/_mcp/server.

# Submit leads to an agent

POST https://api.simz.com/api/lead-receive-service/agent/receiveLead/{agentId}
Content-Type: application/json

Submit one or more leads to a specific SimZ agent for outbound calling.

Reference: https://docs.simz.com/api-reference/sim-z-lead-receive-api/lead-receive/submit-leads

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: simz-integration
  version: 1.0.0
paths:
  /api/lead-receive-service/agent/receiveLead/{agentId}:
    post:
      operationId: submit-leads
      summary: Submit leads to an agent
      description: Submit one or more leads to a specific SimZ agent for outbound calling.
      tags:
        - subpackage_leadReceive
      parameters:
        - name: agentId
          in: path
          description: SimZ agent ID that should receive the leads.
          required: true
          schema:
            type: string
        - name: X-Company-API-Key
          in: header
          description: Company API key issued by SimZ.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: All submitted leads were accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadSubmissionResponse'
        '400':
          description: Invalid request body or lead data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid company API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            The company has insufficient credits. The lead batch was not created
            and no leads were queued for calling. Add credits before
            resubmitting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsResponse'
        '404':
          description: Agent not found or unavailable for this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            SimZ could not verify the company credit balance. The request fails
            closed and no leads were queued. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingCheckFailedResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadSubmissionRequest'
servers:
  - url: https://api.simz.com
    description: Production API
components:
  schemas:
    LeadInput:
      type: object
      properties:
        phoneNumber:
          type: string
          description: Lead phone number. E.164 is recommended.
        firstName:
          type:
            - string
            - 'null'
        lastName:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
          format: email
        salesforceId:
          type:
            - string
            - 'null'
          description: Optional CRM record ID.
        campaignType:
          type:
            - string
            - 'null'
          description: Optional campaign identifier.
        customData:
          type:
            - object
            - 'null'
          additionalProperties:
            description: Any type
          description: >-
            Client-defined metadata preserved by SimZ and returned in supported
            webhook payloads.
      required:
        - phoneNumber
      title: LeadInput
    LeadSubmissionOptions:
      type: object
      properties:
        priority:
          type:
            - string
            - 'null'
          description: Optional processing priority.
        enableAMD:
          type:
            - boolean
            - 'null'
          description: >-
            Optional answering-machine detection flag when enabled for your
            account.
        webhookUrl:
          type:
            - string
            - 'null'
          format: uri
          description: Optional per-request webhook URL when enabled for your account.
      title: LeadSubmissionOptions
    LeadSubmissionRequest:
      type: object
      properties:
        leads:
          type: array
          items:
            $ref: '#/components/schemas/LeadInput'
          description: Leads to submit to the target agent.
        options:
          $ref: '#/components/schemas/LeadSubmissionOptions'
      required:
        - leads
      title: LeadSubmissionRequest
    LeadSubmissionError:
      type: object
      properties:
        index:
          type: integer
          description: Zero-based index of the rejected lead in the request.
        code:
          type: string
        message:
          type: string
      title: LeadSubmissionError
    LeadSubmissionResponse:
      type: object
      properties:
        success:
          type: boolean
        batchId:
          type:
            - string
            - 'null'
          description: Batch identifier for the submitted leads when returned.
        accepted:
          type: integer
        rejected:
          type: integer
        errors:
          type: array
          items:
            $ref: '#/components/schemas/LeadSubmissionError'
      title: LeadSubmissionResponse
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        code:
          type: string
        message:
          type: string
      title: ErrorResponse
    InsufficientCreditsResponseData:
      type: object
      properties:
        agentId:
          type: string
        companyId:
          type: string
        totalCredits:
          type: integer
          description: Company credit balance at the time of the check.
        totalLeads:
          type: integer
          description: Total number of leads in the submission.
        acceptedLeads:
          type: integer
          description: Always 0 because the batch was not created.
        rejectedLeads:
          type: integer
          description: Number of leads that were not queued.
        reason:
          type: string
        actionRequired:
          type: string
      title: InsufficientCreditsResponseData
    InsufficientCreditsResponse:
      type: object
      properties:
        success:
          type: boolean
        code:
          type: string
        message:
          type: string
        data:
          $ref: '#/components/schemas/InsufficientCreditsResponseData'
      description: >-
        Returned when the request is valid and the agent exists, but the company
        credit balance is zero or below. No lead batch is created and no leads
        are queued for calling.
      title: InsufficientCreditsResponse
    BillingCheckFailedResponseData:
      type: object
      properties:
        agentId:
          type: string
        companyId:
          type: string
      title: BillingCheckFailedResponseData
    BillingCheckFailedResponse:
      type: object
      properties:
        success:
          type: boolean
        code:
          type: string
        message:
          type: string
        data:
          $ref: '#/components/schemas/BillingCheckFailedResponseData'
      description: >-
        Returned when SimZ cannot verify the company credit balance. The request
        fails closed and no leads are queued.
      title: BillingCheckFailedResponse
  securitySchemes:
    companyApiKey:
      type: apiKey
      in: header
      name: X-Company-API-Key
      description: Company API key issued by SimZ.

```

## Examples

### Example 1



**Request**

```json
{
  "leads": [
    {
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": {
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      }
    }
  ],
  "options": {
    "priority": "normal"
  }
}
```

**Response**

```json
{
  "success": true,
  "batchId": "batch_987654321",
  "accepted": 1,
  "rejected": 0,
  "errors": []
}
```

**SDK Code**

```python
import requests

url = "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId"

payload = {
    "leads": [
        {
            "phoneNumber": "+14155552671",
            "firstName": "Michael",
            "lastName": "Thompson",
            "customData": {
                "leadId": "LEAD-789",
                "campaignTag": "summer-sale-2024"
            }
        }
    ],
    "options": { "priority": "normal" }
}
headers = {
    "X-Company-API-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId';
const options = {
  method: 'POST',
  headers: {'X-Company-API-Key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"leads":[{"phoneNumber":"+14155552671","firstName":"Michael","lastName":"Thompson","customData":{"leadId":"LEAD-789","campaignTag":"summer-sale-2024"}}],"options":{"priority":"normal"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId"

	payload := strings.NewReader("{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Company-API-Key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Company-API-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")
  .header("X-Company-API-Key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId', [
  'body' => '{
  "leads": [
    {
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": {
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      }
    }
  ],
  "options": {
    "priority": "normal"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Company-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Company-API-Key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Company-API-Key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "leads": [
    [
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": [
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      ]
    ]
  ],
  "options": ["priority": "normal"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2



**Request**

```json
{
  "leads": [
    {
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": {
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      }
    }
  ],
  "options": {
    "priority": "normal"
  }
}
```

**Response**

```json
{
  "success": true,
  "batchId": "batch_987654321",
  "accepted": 1,
  "rejected": 0,
  "errors": []
}
```

**SDK Code**

```python
import requests

url = "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId"

payload = {
    "leads": [
        {
            "phoneNumber": "+14155552671",
            "firstName": "Michael",
            "lastName": "Thompson",
            "customData": {
                "leadId": "LEAD-789",
                "campaignTag": "summer-sale-2024"
            }
        }
    ],
    "options": { "priority": "normal" }
}
headers = {
    "X-Company-API-Key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId';
const options = {
  method: 'POST',
  headers: {'X-Company-API-Key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"leads":[{"phoneNumber":"+14155552671","firstName":"Michael","lastName":"Thompson","customData":{"leadId":"LEAD-789","campaignTag":"summer-sale-2024"}}],"options":{"priority":"normal"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId"

	payload := strings.NewReader("{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Company-API-Key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Company-API-Key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")
  .header("X-Company-API-Key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId', [
  'body' => '{
  "leads": [
    {
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": {
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      }
    }
  ],
  "options": {
    "priority": "normal"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Company-API-Key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Company-API-Key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"leads\": [\n    {\n      \"phoneNumber\": \"+14155552671\",\n      \"firstName\": \"Michael\",\n      \"lastName\": \"Thompson\",\n      \"customData\": {\n        \"leadId\": \"LEAD-789\",\n        \"campaignTag\": \"summer-sale-2024\"\n      }\n    }\n  ],\n  \"options\": {\n    \"priority\": \"normal\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Company-API-Key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "leads": [
    [
      "phoneNumber": "+14155552671",
      "firstName": "Michael",
      "lastName": "Thompson",
      "customData": [
        "leadId": "LEAD-789",
        "campaignTag": "summer-sale-2024"
      ]
    ]
  ],
  "options": ["priority": "normal"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.simz.com/api/lead-receive-service/agent/receiveLead/agentId")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```