Getting Started

The KrickTalk Partner API lets your application place phone calls on behalf of the customers you integrate with, and look up the people it can place them as.

It is built for server-to-server use. Requests are authenticated with a bearer token issued to a service user we provision for your integration.

Base URL

What you need before you start

1. Service user credentials — a username and password we issue you. Contact KrickTalk to have them provisioned.
2. At least one active integration. You may act on a customer's domain only while your integration on that domain is enabled. This is what confines your credentials to your own customers, and it is checked on every request. See Why a request is refused.

Your first call, end to end

1. Get a token

curl -X POST https://partner-api.kricktalk.com/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "••••••••"}'

The response contains an access_token, good for one hour:

{
  "access_token": "fb79ea2e621bebff9e68ac2a543b1438",
  "refresh_token": "146cd61dc89b7c1fe44dbc9209daac04",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": "9999",
  "domain": "yourpartner.kricktalk"
}

🚧

domain is your own domain, not a customer's

That value identifies the domain your service user lives in. Every endpoint here is addressed as /v1/domains/{domain_id}/…, where domain_id is the customer's domain, like yourcustomer.kricktalk. Putting your own domain there returns 403 unless you happen to hold an integration on it.

See Authentication.

2. Find someone to call as

A call is placed as one of the customer's users — their phone rings first, then we dial the destination and bridge the two. So you need their extension:

curl https://partner-api.kricktalk.com/v1/domains/yourcustomer.kricktalk/users \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "users": [
    { "user_id": "101", "first_name": "Dana", "last_name": "Reed" },
    { "user_id": "102", "first_name": "Sam", "last_name": "Ortiz" }
  ]
}

🚧

A "user" and an "extension" are sort of the same...

Technically, they are different entities, but they can be thought of and used interchangeably.

Your demo domain should have a common user, 101, from which you can place test calls while developing. If this isn't the case, contact us.

See Listing users.

3. Place the call

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"
  }'

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

Extension 101's phone rings. When they answer, we dial +18015551212.

Store call_id against your own record of the call. When the call completes, KrickTalk sends a call_log.created webhook carrying the outcome — answered or missed, duration, recording — and call_id is what you match it against. See Placing a call.

How access is decided

Two independent checks run on every request, and both must pass:

The second is the one that surprises people. Valid credentials and the right permission still will not let you touch a domain you do not integrate with — and a customer disabling your integration revokes your access to their domain immediately, without anything changing about your credentials.

Next

• Authentication — token lifetime, refreshing, and handling expiry
• Listing users
• Placing a call
• Errors and rate limits