Skip to content
Talki DevelopersBeta

Retrieve a service

GET
/v1/services/{service_id}
curl --fail-with-body -X GET 'https://api.talki.it/v1/services/45c470b7-592a-42cd-8ce8-5d7a0a497d26' \
  -H "Authorization: Bearer $TALKI_API_KEY"

Return one active or inactive service belonging to the account. Requires services:read. Limited to 600 requests per minute per account (API key) or per installation (OAuth).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
service_id
required
Service Id
string

Header Parameters

Section titled “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.

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
Service

One bookable thing the business offers. Capacity is published on Resource, not here; Resource.services links the two. Inactive services stay in the feed: filter on is_active for a snapshot, never while syncing. A deleted service leaves the feed; service.deleted announces it, with the service as it was. Without the events, reconcile deletions with a full walk from no cursor.

object
id
required
Id

Opaque Talki service identifier.

string
location_id
required
Location Id

The location that offers it (GET /v1/locations). Each location has services of its own, so two locations selling the same thing have one service each, with its own id, price and availability. Never null, and it never changes.

string
name
required
Name

What the business calls this service.

string
description
required
Any of:
string
price
required
Any of:
string
duration_minutes
required
Any of:
integer
booking_mode
required
Booking Mode

duration for a timed slot (the common case), or day_range for a stay spanning whole nights or days: a hotel room, a multi-day rental. Read this before duration_minutes; the two modes are booked with different information.

string
Allowed values: duration day_range
range_unit
required
Any of:

nights (check-out day is free again) or days (the whole last day is held).

string
Allowed values: nights days
min_stay
required
Any of:
integer
max_stay
required
Any of:
integer
checkin_time
required
Any of:
string
checkout_time
required
Any of:
string
asks_quantity
required
Asks Quantity

True when a booking of this service carries a count — covers, people, items — and the assistant asks for it. False when one booking always means one unit.

boolean
quantity_label
required
Any of:
string
min_quantity
required
Min Quantity

Smallest count a booking may carry.

integer
max_quantity
required
Any of:
integer
is_active
required
Is Active

False when the business has switched the service off. It is still published — see the note on this object — but it is not bookable and should not be offered.

boolean
created_at
required
Created At

When the service was added, RFC 3339 UTC.

string format: date-time
updated_at
required
Updated At

Last change to the service, RFC 3339 UTC. Show it to a human; do not sync on it, for the reason given on Appointment.updated_at.

string format: date-time
Example
{
  "id": "45c470b7-592a-42cd-8ce8-5d7a0a497d26",
  "location_id": "0b7d4e19-8a2c-4f61-9d3e-5c1a7b2f8e40",
  "name": "Haircut",
  "description": "Wash and cut",
  "price": "30€",
  "duration_minutes": 30,
  "booking_mode": "duration",
  "range_unit": null,
  "min_stay": null,
  "max_stay": null,
  "checkin_time": null,
  "checkout_time": null,
  "asks_quantity": false,
  "quantity_label": null,
  "min_quantity": 1,
  "max_quantity": null,
  "is_active": true,
  "created_at": "2026-08-01T08:00:00Z",
  "updated_at": "2026-09-10T10:30:00Z"
}

Headers

Section titled “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.

400

Section titled “400”

Talki-Version, or the credential’s pin, names a version this API does not serve.

Media typeapplication/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": "unsupported_version",
    "message": "'2025-01-01' is not a supported API version. Supported: 2026-10-01.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

401

Section titled “401”

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

Media typeapplication/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": "authentication_error",
    "code": "invalid_credentials",
    "message": "The supplied API credential is invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

402

Section titled “402”

The account does not have an active subscription.

Media typeapplication/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": "permission_error",
    "code": "subscription_inactive",
    "message": "This account does not have an active subscription.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

403

Section titled “403”

The account or credential may not perform this request.

Media typeapplication/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": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not have the required scope.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

404

Section titled “404”

No service with this ID exists in the authenticated account.

Media typeapplication/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": "resource_not_found",
    "message": "No such service.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

429

Section titled “429”

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

Media typeapplication/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": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the interval in Retry-After.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “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

Section titled “500”

An unexpected error occurred.

Media typeapplication/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": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Quote the request_id when reporting it.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string
Example
req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.