Complete onboarding

POST

/v1/account/complete_onboarding

curl --fail-with-body -X POST 'https://api.talki.it/v1/account/complete_onboarding' \
  -H "Authorization: Bearer $TALKI_API_KEY" \
  -H "Idempotency-Key: onboarding-done"

Mark the account’s setup as finished, so the Talki app does not open its setup wizard. Idempotent; it is never undone. Requires account:write. Limited to 120 requests per minute per account (API key) or per installation (OAuth).

Authorizations

ApiKeyAuth

Parameters

Header Parameters

Talki-Version

string

Example

2026-10-01

Serve this one request at the given dated contract version instead of the credential’s pin. An unsupported value is refused with 400 unsupported_version, never downgraded.

Idempotency-Key

string

<= 255 characters

Unique key for this logical write. Reuse it only when retrying the same method, path, query and body. Required on appointment writes, on creating a service, a resource, a closure, a tag, a caller rule or a document, and on teaching the assistant; optional on every other write. Retained for 24 hours: a retry with the same key gets the first response again, marked Idempotency-Replayed: true, and a refusal that holds until the state changes (a time taken, a list full) is replayed too. A response a retry can change is not kept when the request saved nothing, and the retry runs the request again: a 400 asking for a different request (invalid_parameter, invalid_cursor, export_too_large, unknown_scenario, no_services_requested, stay_too_short, stay_too_long, stay_dates_invalid), a 415, a 409 request_conflict, document_not_ready or check_in_progress, a 412, a 429 and a 5xx.

Example

onboarding-done

Responses

200

Successful Response

application/json

Account

The account a credential belongs to, and everything its owner sets up for the assistant: the business name and texts, the voice, the opening and greeting, the switches, the transfer numbers, and the line that forwards to Talki. GET /v1/account needs only account:read, which makes it the call to validate a new credential. The settings are those of one location: the main one, or the one ?location_id= names, the switches included. Only the account’s own fields (id, timezone, livemode, test, multi_sede, onboarding_completed and call_auto_archive_days) read the same at every location. The response’s ETag covers every writable field at that location; send it back as If-Match on PATCH /v1/account with the same location_id. account.updated reports a change to the main location’s settings or to call_auto_archive_days, location.settings_updated one to another location’s settings, its switches included.

object

required

Opaque Talki account identifier.

string

location_id

required

Location Id

The location these settings are of, an id from GET /v1/locations: the one the request named with location_id, or the main location when it named none.

string

business_name

required

Any of:

string
null

string

timezone

required

Timezone

IANA timezone all naive local times for this account resolve against.

string

livemode

required

Livemode

False when this credential does not act on real data: a test-mode key (talki_test_…), or an app installed on a developer sandbox or on a test account. Webhook envelopes carry the same flag.

boolean

test

required

Test

True for a test account your app created with "test": true on POST /oauth/managed-accounts. It has no Talki number, nobody is billed for it or emailed, and it is erased seven days after it was created. Its livemode is false.

boolean

business_information

required

Any of:

string
null

string

instructions

required

Any of:

string
null

string

voice

required

Voice

The voice the assistant speaks with on calls. One of the ids listed by GET /v1/voices.

string

answers_as

required

Which name the assistant answers calls in and speaks for: business uses business_name, owner uses the account holder’s own name. If the chosen name is empty, the other one is used.

string

Allowed values: business owner

greeting

required

Any of:

string
null

string

call_opening

required

Any of:

string
null

string

multilingual_enabled

required

Multilingual Enabled

True when the assistant may switch to English, French, German or Spanish to follow the caller. False keeps every call in Italian. The opening is always in Italian.

boolean

languages

required

AccountLanguages

The languages calls may be held in, derived from multilingual_enabled. Read only.

object

primary

required

Primary

The language every call opens in, before the caller has said anything. Always it today.

string

supported

required

Supported

Every language the assistant may speak, primary first: it alone while multilingual_enabled is false, otherwise it, en, fr, de and es. More may be added. Read only: change it through multilingual_enabled.

Array<string>

service_area

required

Any of:

string
null

string

transfer_numbers

required

Transfer Numbers

People or lines the assistant may hand a call over to. Empty when the assistant never transfers calls.

Array<object>

TransferNumber

A person or line the assistant may hand a call over to.

object

label

required

Label

Who answers at this number, such as “Reception” or “Dr. Bianchi”. The assistant uses it to pick the right target for a caller, and call.transferred reports it as target_label.

string

phone

required

Phone

The number, E.164.

string

bookings_enabled

required

Bookings Enabled

True when the assistant books, moves and cancels appointments on calls. False makes it answer questions and take messages only. Does not affect the appointment endpoints of this API.

boolean

unresolved_requests_enabled

required

Unresolved Requests Enabled

True when the assistant offers to record a question it cannot answer, so the business can follow up. Recorded questions are listed by GET /v1/unresolved_requests.

boolean

remember_callers

required

Remember Callers

True when the assistant recognises returning callers from the contact book and keeps notes about them for their next call. False treats every call as a first call and keeps nothing about the caller after it ends.

boolean

notify_on_every_call

required

Notify On Every Call

True when the owner gets a push notification on the Talki mobile app after each call, with its summary. Push only, and only on phones where the owner is signed in to the app with notifications allowed; bookings, conflicts and unresolved questions push whatever this says. Talki sends no email or SMS per call: build those on the call.ended and appointment.created events.

boolean

notify_on_incoming_call

required

Notify On Incoming Call

True when the owner gets a push notification on the Talki mobile app while a call is ringing, naming the caller, for every caller. Callers marked VIP push whatever this says. Push only, as for notify_on_every_call.

boolean

store_transcripts

required

Store Transcripts

True when the words of each call to this location are kept, readable through GET /v1/calls/{id}/transcript. Setting it to false deletes the transcripts already stored for this location’s calls; call records and summaries are kept.

boolean

phone_number

required

Any of:

string
null

string

forwarding_number

required

Any of:

string
null

string

line

required

AccountLine

The location’s Talki number, its line that forwards to it, and whether that forwarding has been proven. Read only. The same as Location.line.

object

phone_number

required

Any of:

string
null

string

forwarding_number

required

Any of:

string
null

string

status

required

no_number while the account has no Talki number. unverified until a forwarding check of the current forwarding_number has succeeded, including while no forwarding_number is set. verified once one has. It proves forwarding was on at verified_at, not that it still is: the business can switch it off at its carrier without Talki knowing. Changing forwarding_number returns it to unverified. A check that finds no forwarding does not change it; read that outcome from GET /v1/forwarding_check.

string

Allowed values: no_number unverified verified

verified_at

required

Any of:

string
null

string format: date-time

call_auto_archive_days

required

Any of:

integer
null

integer

Allowed values: 7 30 90 180

multi_sede

required

Multi Sede

True when the account works from several locations, or may add them: show locations (GET /v1/locations) to the owner only when true. False for an account that has only ever had its main location and cannot add another; it still has that one location, every record still carries its location_id, and nothing changes shape when this turns true. Read only.

boolean

onboarding_completed

required

Onboarding Completed

True once the account has finished setting up its assistant. While false, the Talki app opens its setup wizard. Set it with POST /v1/account/complete_onboarding; it never goes back to false.

boolean

Example

{
  "id": "f7e39b9a-1ac8-45e4-93da-2600f17cb286",
  "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40",
  "business_name": "Studio Bellini",
  "timezone": "Europe/Rome",
  "livemode": true,
  "test": false,
  "business_information": "Free parking in the courtyard behind the salon. We do not sell gift cards.",
  "instructions": null,
  "voice": "Sulafat",
  "answers_as": "business",
  "call_auto_archive_days": null,
  "greeting": null,
  "call_opening": null,
  "multilingual_enabled": true,
  "languages": {
    "primary": "it",
    "supported": [
      "it",
      "en",
      "fr",
      "de",
      "es"
    ]
  },
  "service_area": "Bergamo e provincia",
  "transfer_numbers": [],
  "bookings_enabled": true,
  "unresolved_requests_enabled": true,
  "remember_callers": true,
  "store_transcripts": true,
  "notify_on_every_call": true,
  "notify_on_incoming_call": false,
  "phone_number": "+390350000001",
  "forwarding_number": "+393331112222",
  "line": {
    "phone_number": "+390350000001",
    "forwarding_number": "+393331112222",
    "status": "verified",
    "verified_at": "2026-10-07T09:30:12Z"
  },
  "multi_sede": true,
  "onboarding_completed": true
}

Headers

X-Request-Id

string

Identifier to include when contacting Talki support.

Talki-Version

string

Example

2026-10-01

The dated contract version this response was served at.

ETag

string

Example

"9c1e4b7a2f0d4c68b35e7a1d9f2c6b40"

Strong entity tag of the writable content. Send it as If-Match on the next write. Absent on a response replayed from an Idempotency-Key; read again for a current one.

Idempotency-Replayed

string

Allowed values: true

true when this response was replayed from a prior request with the same key.

400

A parameter, cursor, body field, or required idempotency key is invalid, or Talki-Version names an unsupported version (unsupported_version).

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

Stable machine code; branch on this, not on message. Known codes: invalid_credentials, insufficient_scope, account_closed, subscription_inactive, plan_upgrade_required, plan_feature_unavailable, forbidden, livemode_required, sandbox_api_key_required, unsupported_version, invalid_parameter, invalid_cursor, method_not_allowed, resource_not_found, conflict, precondition_failed, payload_too_large, export_too_large, idempotency_key_required, idempotency_key_reuse, request_in_progress, request_conflict, rate_limit_exceeded, ip_rate_limited, internal_error, api_error, booking_refused, appointment_cancelled, appointment_not_cancelled, unresolved_request_not_resolved, faq_full, document_not_ready, unsupported_file_type, service_has_upcoming_bookings, resource_is_default, resource_required_by_service, capacity_below_committed, capacity_below_service_requirement, resource_too_small, tag_limit_reached, caller_rule_limit_reached, transcript_not_available, trial_suspended, account_suspended, phone_number_missing, forwarding_number_missing, forwarding_number_invalid, check_in_progress, check_quota_exceeded, checks_busy, check_call_failed, agent_test_session_full, agent_test_unavailable, unknown_scenario, sandbox_not_ready, too_many_keys, key_not_active, key_already_rolled, invalid_registration, client_disabled, client_changed, delivery_in_progress, events_url_unset, events_paused, event_unsubscribed, account_refused, installation_inactive, invalid_client, invalid_request, unauthorized_client, access_denied, invalid_scope, slot_unavailable, capacity_exhausted, service_exclusion, closed_day, in_the_past, outside_hours, service_inactive, location_inactive, service_deleted, no_services_requested, party_too_large, stay_too_short, stay_too_long, stay_dates_invalid. New codes may be added; treat an unknown one by its HTTP status.

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "One or more request values are invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

401

The credential is missing, malformed, expired, revoked, or unknown.

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "The supplied API credential is invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

402

The account does not have an active subscription.

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "permission_error",
    "code": "subscription_inactive",
    "message": "This account does not have an active subscription.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

403

The account or credential may not perform this request.

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not have the required scope.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

409

The write conflicts with current state or a previous idempotency key use.

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was already used for a different request.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

429

The account or installation exceeded its request rate (rate_limit_exceeded), or the calling address did (ip_rate_limited).

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the interval in Retry-After.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

Retry-After

integer

Seconds to wait before retrying.

X-RateLimit-Limit

string

The budget of the window that was exceeded. Absent on ip_rate_limited.

X-RateLimit-Remaining

integer

Requests left in the window. Absent on ip_rate_limited.

X-RateLimit-Reset

integer

When the window resets, in Unix seconds. Absent on ip_rate_limited.

500

An unexpected error occurred.

application/json

Every error answer has this shape.

object

error

required

The error itself. Branch on code; message is for people.

object

type

required

string

Allowed values: authentication_error permission_error invalid_request conflict rate_limit_error api_error

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Quote the request_id when reporting it.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.