Placing a Call

Click-to-call. You name a user in the customer's domain and a destination; we ring the user first, and when they answer we dial the destination and bridge them together.

That ordering is the thing to design your interface around. From the user's point of view they click a button and their own desk phone rings — so the label you send as callee_id matters, because it is what tells them who they are about to be connected to.

Requires appropriate permissions and an active integration on the domain.

Request

curl -X POST https://partner-api.kricktalk.com/v1/domains/yourcustomer.kricktalk/calls \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_extension": "101",
    "destination": "+18015551212",
    "callee_id": "Dana Reed"
  }'

Caller ID

Omit caller_id unless you have a specific reason. The defaults are:

• External destination → the domain's configured outbound number, so the call appears to come from the business.
• Internal destination (an extension) → from_extension, so a colleague sees who is calling.

If you do send one, it has to be consistent with the destination: for an external destination it must be a valid US number in E.164 form that belongs to the customer's phone system; for an internal destination it must equal from_extension. Anything else is a 400.

Response

{
  "call_id": "C2C-3f9a2b7c1d4e5f60718293a4b5c6d7e8",
  "status": "originating",
  "domain_id": "yourcustomer.kricktalk",
  "from_extension": "101",
  "destination": "+18015551212"
}

❗️

200 means accepted, not connected

status is originating: the telephony platform took the request and is ringing from_extension. It does not mean anyone answered, and the call may still fail — nobody picks up, the destination is busy, the number is unreachable.

Do not tell your user "call connected" on this response. "Calling…" is accurate; the outcome arrives later.

destination is echoed back as dialed — normalized to E.164 when it is a number, unchanged when it is an extension.

Learning how the call went

This endpoint tells you the call was accepted. What actually happened — answered, missed, how long it lasted, the recording — arrives later, on the call_log.created webhook KrickTalk sends when the call completes.

Store call_id and match it against payload.origination_call_id on that webhook:

{
  "type": "call_log.created",
  "payload": {
    "origination_call_id": "C2C-3f9a2b7c1d4e5f60718293a4b5c6d7e8",
    "status": "answered",
    "duration_seconds": 64,
    "recording_url": "https://…"
  }
}

The two values are equal, so a plain string comparison is enough — no prefix matching or trimming.

origination_call_id is null on calls you did not place through this endpoint, which is most of them: anything inbound, or dialed from a handset. It may also carry an id you do not recognize, which means the call was started from KrickTalk's own click-to-call rather than by you. In both cases there is nothing to join to, and that is expected.

📘

Why not match on call_main_uuid?

call_main_uuid identifies the call in the telephony platform, and a click-to-call is made of two legs — one ringing your user, one dialing the destination. Which leg's identifier ends up in call_main_uuid varies, so joining on it would match some of your originations and silently miss others. origination_call_id is populated from either leg and is the field to use.

Quote call_id in any support request, too — it is how KrickTalk finds a specific attempt in our logs.

Errors

Validation errors name the field:

{
  "errors": [
    {
      "destination": [
        "Please provide either a valid US number in E.164 format or 3 - 5 digit extension."
      ]
    }
  ]
}

A 502 carries the call_id, so a failed attempt can be traced:

{ "message": "Failed to originate call.", "call_id": "C2C-3f9a2b7c..." }

"Integration is not configured for click-to-call"

A 400 with this message means the customer's integration has no outbound number set, so there is no caller ID to present for an external call. It is a configuration gap on our side, not something your request can work around — ask KrickTalk to set the number for that domain.

Calls to an internal extension still work in this state, because they use from_extension as the caller ID and need no outbound number.

Trying it safely

1. Pass your demo domain_id in the URL
2. Set destination to a number you control (your demo domain should have one).
3. Set from_extension to 101 (demo domain should have a user 101).
4. Set desintation to an external (e.g. mobile) DID.
5. Open the KrickTalk portal and log into the webphone as user 101. This is important, since you must have a registered device to intercept the ring.
6. Submit the request and answer the web phone when it rings.