Docs › Connect › Connect API

Connect API

Benefits

  • Instantaneous Lead Engagement: Connect sales executives with potential customers the moment they express interest, maximising engagement and conversion opportunities, typically within ~30 seconds.
  • Streamlined Workflow: Automate the call connection process, allowing sales Executives to focus on building rapport and closing deals.
  • Enhanced Efficiency: Eliminate manual call initiation, saving valuable time for your sales team.

Example Workflow

  1. A prospective customer submits an enquiry on your website, including their phone number, about a car they are interested in.
  2. Your web server sends an API request to Connect, requesting to connect your sales executive to the customer.
  3. Connect calls your sales executive, informs them about the specific enquiry via a whisper message, and asks for confirmation to connect to the prospect.
  4. Upon confirmation, the customer is called, and both calls are bridged.
  5. This process can happen while the customer is still browsing the online advert, typically within ~30 seconds.

How to Trigger a Connect

Request example:

curl -sX POST https://next.logimeter.com/v1/connect/ \
--header 'Authorization: Token xxxxxxx_your_token_xxxxx' \
--header 'Content-Type: application/json' \
--data '{
  "call_term_callbacks": ["https://your-server.com/connect/callbacks/"],
  "whisper": "A potential customer has shown interest in your Citi Golf",
  "leg_a": [{"number": "27821234567", "name": "Jane Smith", "reference": "agent123"}],
  "leg_b": [{"number": "27831112222", "name": "John Doe"}],
  "company": {
    "reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190",
    "name": "Trask Industries"
  }
}'
const response = await fetch('https://next.logimeter.com/v1/connect/', {
  method: 'POST',
  headers: {
    'Authorization': 'Token xxxxxxx_your_token_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    call_term_callbacks: ['https://your-server.com/connect/callbacks/'],
    whisper: 'A potential customer has shown interest in your Citi Golf',
    leg_a: [{ number: '27821234567', name: 'Jane Smith', reference: 'agent123' }],
    leg_b: [{ number: '27831112222', name: 'John Doe' }],
    company: {
      reference: '6e7d1f48-2ca1-4ef4-a433-a3fa765ff190',
      name: 'Trask Industries'
    }
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`Connect request failed (${response.status}): ${JSON.stringify(error)}`);
}

const data = await response.json();
console.log('Connect UUID:', data.uuid);
import requests

resp = requests.post(
    'https://next.logimeter.com/v1/connect/',
    headers={
        'Authorization': 'Token xxxxxxx_your_token_xxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'call_term_callbacks': ['https://your-server.com/connect/callbacks/'],
        'whisper': 'A potential customer has shown interest in your Citi Golf',
        'leg_a': [{'number': '27821234567', 'name': 'Jane Smith', 'reference': 'agent123'}],
        'leg_b': [{'number': '27831112222', 'name': 'John Doe'}],
        'company': {
            'reference': '6e7d1f48-2ca1-4ef4-a433-a3fa765ff190',
            'name': 'Trask Industries',
        },
    },
)

if not resp.ok:
  print(resp.status_code, resp.json())
  resp.raise_for_status()

data = resp.json()
print('Connect UUID:', data.get('uuid'))

Endpoints

POST /v1/connect/ Create a Connect and start dialling
GET /v1/connect/ List Connect requests for your partner (paginated)
GET /v1/connect/{uuid}/ Retrieve one Connect by UUID

All endpoints require Authorization: Token … and the can_lead_connect permission. List/retrieve return the same JSON shape as the create response, with leg progress fields populated over time.

Retrieve Connect — code example

curl -s "https://next.logimeter.com/v1/connect/1ab5579f-88af-4873-9433-b595a8d5738d/" \
  -H "Authorization: Token xxxxxxx_your_token_xxxxx"
const response = await fetch(
  'https://next.logimeter.com/v1/connect/1ab5579f-88af-4873-9433-b595a8d5738d/',
  { headers: { Authorization: 'Token xxxxxxx_your_token_xxxxx' } }
);
const connect = await response.json();
console.log(connect.state.name);
import requests

resp = requests.get(
    'https://next.logimeter.com/v1/connect/1ab5579f-88af-4873-9433-b595a8d5738d/',
    headers={'Authorization': 'Token xxxxxxx_your_token_xxxxx'},
)
resp.raise_for_status()
connect = resp.json()

Responses

After calling POST /v1/connect/, check the HTTP status code first, then parse the JSON body. On success, store the returned uuid — you will use it to track this Connect and to match incoming call events. See Connect Fields for the full request and response field reference.

201 Created

The Connect was accepted and outbound dialling has started. state.name is typically PENDING while the agent (leg_a) and customer (leg_b) are being called. 

{
  "url": "https://next.logimeter.com/v1/connect/1ab5579f-88af-4873-9433-b595a8d5738d/",
  "uuid": "1ab5579f-88af-4873-9433-b595a8d5738d",
  "reference": null,
  "create_stamp": "2024-08-08T09:56:23.915931Z",
  "modify_stamp": "2024-08-08T09:56:23.915931Z",
  "call_term_callbacks": [
    "https://your-server.com/connect/callbacks/"
  ],
  "whisper": "A potential customer has shown interest in your Citi Golf",
  "recorded": true,
  "state": {
    "name": "PENDING",
    "description": "The call is progressing normally..."
  },
  "connect_type": "LEAD_CONNECT",
  "call_distribution": "SINGLE",
  "company": {
    "name": "Trask Industries",
    "reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190"
  },
  "partner": {
    "name": "your-partner-name"
  },
  "leg_a": [
    {
      "number": "27821234567",
      "name": "Jane Smith",
      "reference": "agent123",
      "confirmed": false,
      "bridged": false,
      "order": 1,
      "dial_stamp": null,
      "answer_stamp": null,
      "end_stamp": null
    }
  ],
  "leg_b": [
    {
      "number": "27831112222",
      "name": "John Doe",
      "reference": null,
      "confirmed": false,
      "bridged": false,
      "order": 1,
      "dial_stamp": null,
      "answer_stamp": null,
      "end_stamp": null
    }
  ],
  "calls": [],
  "confirmed_call": []
}
FieldMeaning
uuid Unique identifier for this Connect. Use it when polling or receiving call events.
state.name Current Connect lifecycle state (e.g. PENDING, then progressing as calls connect).
leg_a / leg_b Echo of the agent and customer legs, with call progress fields populated as dialling proceeds.
call_term_callbacks URLs that will receive call metadata when the Connect completes (plus any partner/company URLs configured in Logimeter).
callall_callgroup Present when leg_a was resolved from a call group via vehicle.
401 Unauthorized

Returned when the Authorization header is missing or the token is invalid.

{
  "detail": "Authentication credentials were not provided."
}
403 Forbidden

Returned when the authenticated user cannot create Connects. Common causes:

  • User has no linked partner — Partner does not exist for user your_username.
  • User lacks Connect permission — You do not have permission to perform this action.
{
  "detail": "Partner does not exist for user your_username."
}
500 Internal Server Error

Can occur after the Connect record is already saved — for example when no voice switches are available (No Switches could be retrieved!). The Connect may exist with state.name: FAILED. Check by uuid or reference before retrying to avoid duplicates. 

{
  "detail": "No Switches could be retrieved!"
}

Validation errors (400 Bad Request)

When one or more request fields fail validation, the API returns 400 Bad Request. The response body is a JSON object: field names map to arrays of human-readable error strings. Cross-field problems usually appear under non_field_errors.

Scenario What triggers it Where the error appears
Invalid agent phone number leg_a[].number uses local format (083...), includes +, or has an invalid length leg_a[0].number
Missing agent details leg_a item omits required name or reference leg_a[0].name or leg_a[0].reference
Invalid customer phone number Same rules as leg_a, applied to leg_b[].number leg_b[0].number
Empty leg list leg_a or leg_b is an empty array leg_a or leg_b
Same number on both legs A number appears in both leg_a and leg_b non_field_errors
Mixed country codes Leg A and Leg B numbers do not share the same country dial code non_field_errors
Invalid callback URL call_term_callbacks is not an array of valid HTTPS URLs call_term_callbacks
Missing company reference company.reference is absent or blank company.reference
Call distribution mismatch Multiple leg_a entries with call_distribution of SINGLE, or multiple legs without a distribution strategy non_field_errors
Unsupported country Number prefix not enabled for partner account leg_a or leg_b
Optional leg_a without call group leg_a omitted with vehicle but company call group not configured non_field_errors
Invalid vehicle brand vehicle.brand not in Logimeter brand catalogue non_field_errors
SEQUENTIAL leg limit Too many A-legs for SEQUENTIAL (company max, default 10) non_field_errors
Lead reference safety-net Duplicate reference with pending call, prior OK, or max retries exceeded non_field_errors

Lead reference safety checks

When reference is provided on a LEAD_CONNECT request, partner-configured guards may return 400:

  • A call is already in progress for this lead.
  • This lead has already had a successful call with the prospect.
  • The maximum retry limit of {N} attempts for this lead has been exceeded.

Omitting reference skips these checks. See Fields → Safety-net.

Example — invalid phone number on leg_a

Request uses a local-format number (0821234567) instead of international digits-only format (27821234567).

{
  "leg_a": [{"number": "0821234567", "name": "Jane Smith", "reference": "agent123"}],
  "leg_b": [{"number": "27831112222"}],
  "company": {"reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190"}
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "leg_a": [
    {
      "number": [
        "Numbers must be in international format, like \"27216714444\""
      ]
    }
  ]
}

Example — missing leg_a.name

{
  "leg_a": [{"number": "27821234567", "reference": "agent123"}],
  "leg_b": [{"number": "27831112222"}],
  "company": {"reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190"}
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "leg_a": [
    {
      "name": ["This field is required."]
    }
  ]
}

Example — same number on both legs

{
  "leg_a": [{"number": "27821234567", "name": "Jane Smith", "reference": "agent123"}],
  "leg_b": [{"number": "27821234567"}],
  "company": {"reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190"}
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "non_field_errors": [
    "The following numbers appear in both the leg_a and leg_b lists: 27821234567"
  ]
}

Example — call_term_callbacks must be an array

{
  "call_term_callbacks": "https://your-server.com/connect/callbacks/",
  "leg_a": [{"number": "27821234567", "name": "Jane Smith", "reference": "agent123"}],
  "leg_b": [{"number": "27831112222"}],
  "company": {"reference": "6e7d1f48-2ca1-4ef4-a433-a3fa765ff190"}
}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "call_term_callbacks": [
    "Expected a list of items but got type \"str\"."
  ]
}

Phone numbers must be digits only in international format — no leading +, spaces, or local prefixes like 0. For South Africa use 11 digits starting with 27 (e.g. 27821234567). Length must be between 9 and 15 digits.