> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.talkif.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.talkif.ai/_mcp/server.

# List phone number usage

GET https://api.talkif.ai/api/v1/phone/numbers/{id}/usage

Returns the flow that answers inbound calls to the number, the Meta lead
form mappings that use it as caller ID, and the unfinished campaigns and
call schedules that dial from it. `canRelease` is `false` while a Meta lead
form mapping uses the number: delete those mappings or point them at another
number before releasing it.

Reference: https://docs.talkif.ai/api-reference/phone-numbers/get-phone-number-usage

## Authentication

- `Authorization` header (bearer token, required) — Pass a JWT access token or an API key (prefixed with `tif_live_`) as a Bearer token.

## Request

### Path parameters

- `id` (string, required) — Phone number ID

## Response

### 200

What uses the phone number

- `campaigns` (list of PhoneNumberUsageCampaign, required) — Campaigns that dial from this number and have not finished
- `canRelease` (boolean, required) — Whether the number can be released now. `false` while any Meta lead form mapping uses it as caller ID: release answers `cannot_delete_has_dependencies` until those mappings are deleted or use another number. The inbound flow, campaigns and schedules never block a release; they stop working once the number is gone.
- `metaLeadForms` (list of PhoneNumberUsageMetaLeadForm, required) — Meta lead form mappings that call new leads from this number
- `phoneNumberId` (string, required) — Phone number these uses belong to
- `schedules` (list of PhoneNumberUsageSchedule, required) — Active or paused call schedules that dial from this number
- `inboundFlow` (PhoneNumberUsageFlow, optional, nullable) — Flow connected to a phone number for inbound calls

## Errors

### 401 Unauthorized Error

Authentication required — token is missing, expired, or invalid

- `code` (enum, required) — Machine-readable error code for programmatic handling
  - Allowed values: `invalid_credentials`, `email_already_exists`, `phone_already_exists`, `contact_phone_already_exists`, `account_suspended`, `account_pending_deletion`, `login_pending_deletion`, `owns_organization_with_members`, `account_deletion_blocked`, `client_update_required`, `account_access_denied`, `token_expired`, `token_invalid`, `token_missing`, `account_header_missing`, `refresh_token_invalid`, `email_already_verified`, `email_verification_code_invalid`, `email_verification_code_expired`, `email_verification_code_used`, `email_service_unavailable`, `phone_already_verified`, `phone_verification_code_invalid`, `bot_check_failed`, `phone_verification_code_expired`, `phone_verification_code_used`, `phone_number_missing`, `email_not_verified`, `disposable_email_not_allowed`, `request_blocked`, `phone_verification_refused`, `sms_service_unavailable`, `mfa_already_enabled`, `mfa_not_enabled`, `mfa_not_setup`, `mfa_code_invalid`, `passkey_not_found`, `password_reset_token_invalid`, `password_reset_token_expired`, `password_reset_token_used`, `password_current_incorrect`, `password_same_as_current`, `invalid_o_auth_state`, `o_auth_provider_error`, `o_auth_already_linked`, `provider_already_connected`, `o_auth_not_linked`, `cannot_unlink_only_auth`, `validation_failed`, `bad_request`, `ring_target_required`, `invalid_json`, `resource_not_found`, `not_found`, `forbidden`, `insufficient_permissions`, `connectors_consent_required`, `already_answered`, `expired`, `conflict`, `resource_already_exists`, `insufficient_balance`, `payment_required`, `subscription_required`, `feature_not_available`, `payment_failed`, `business_rule_violation`, `invalid_state_transition`, `unprocessable_entity`, `rate_limit_exceeded`, `queue_full`, `assistant_quota_exceeded`, `phone_purchase_rate_limited`, `user_phone_not_verified`, `account_not_verified`, `owner_verification_required`, `payment_method_required`, `trial_already_claimed`, `promotion_not_eligible`, `coupon_not_found`, `coupon_not_redeemable`, `coupon_already_redeemed`, `phone_number_not_active`, `phone_number_not_verified`, `phone_number_cannot_initiate_calls`, `flow_not_published`, `provider_call_rejected`, `concurrent_call_limit_exceeded`, `daily_call_limit_exceeded`, `contact_on_dnc_list`, `outside_callable_hours`, `call_already_completed`, `phone_provider_not_active`, `phone_number_already_connected`, `phone_number_not_connected`, `provider_must_be_sip`, `verification_only_for_sip`, `phone_verification_not_started`, `twilio_credentials_required`, `byoc_only`, `phone_already_registered`, `cannot_delete_system_provider`, `phone_number_type_unavailable`, `flow_name_already_exists`, `flow_structure_invalid`, `flow_has_connected_phones`, `flow_version_invalid`, `flow_version_conflict`, `flow_function_name_exists`, `flow_function_not_found`, `flow_generation_failed`, `payment_method_card_only`, `apple_transaction_invalid`, `apple_transaction_account_mismatch`, `sandbox_purchase_not_allowed`, `template_variable_resolution_failed`, `phone_number_in_use`, `phone_number_limit_reached`, `mfa_token_invalid`, `invalid_id_format`, `verification_code_invalid`, `cannot_delete_has_dependencies`, `in_use`, `unsupported_kind`, `offer_taken`, `offer_taken_self`, `offer_expired`, `already_taken`, `takeover_unsupported`, `schedule_not_found`, `schedule_already_paused`, `schedule_not_paused`, `invalid_cron_expression`, `invalid_timezone`, `campaign_not_found`, `campaign_not_draft`, `campaign_no_contacts`, `legal_acceptance_required`, `invitation_not_found`, `invitation_not_pending`, `invitation_expired`, `not_invitation_recipient`, `organization_suspended`, `already_organization_member`, `api_key_invalid`, `api_key_expired`, `api_key_revoked`, `api_key_not_allowed`, `api_key_insufficient_scope`, `api_key_ip_restricted`, `api_key_limit_reached`, `internal_error`, `service_error`, `service_unavailable`, `no_bots_available`, `region_saturated`, `recording_not_available`, `recording_service_not_configured`, `meta_not_configured`, `meta_page_already_connected`, `meta_form_already_mapped`, `meta_api_error`, `meta_lead_unrecoverable`, `unauthorized`
- `detail` (string, required) — Human-readable detail message for this specific error instance
- `status` (integer, required) — HTTP status code (mirrors the response status line)
- `title` (string, required) — Human-readable title for the error category
- `errors` (list of FieldError, optional, nullable) — Field-level validation errors, present when code is `validation_failed`
- `meta` (ErrorResponseMeta, optional, nullable) — Additional context metadata (e.g., retryAfterSecs for rate limits)
- `requestId` (string, optional, nullable) — Unique request identifier for debugging (also in X-Request-Id response header)

### 403 Forbidden Error

`forbidden`

- `code` (enum, required) — Machine-readable error code for programmatic handling
  - Allowed values: `invalid_credentials`, `email_already_exists`, `phone_already_exists`, `contact_phone_already_exists`, `account_suspended`, `account_pending_deletion`, `login_pending_deletion`, `owns_organization_with_members`, `account_deletion_blocked`, `client_update_required`, `account_access_denied`, `token_expired`, `token_invalid`, `token_missing`, `account_header_missing`, `refresh_token_invalid`, `email_already_verified`, `email_verification_code_invalid`, `email_verification_code_expired`, `email_verification_code_used`, `email_service_unavailable`, `phone_already_verified`, `phone_verification_code_invalid`, `bot_check_failed`, `phone_verification_code_expired`, `phone_verification_code_used`, `phone_number_missing`, `email_not_verified`, `disposable_email_not_allowed`, `request_blocked`, `phone_verification_refused`, `sms_service_unavailable`, `mfa_already_enabled`, `mfa_not_enabled`, `mfa_not_setup`, `mfa_code_invalid`, `passkey_not_found`, `password_reset_token_invalid`, `password_reset_token_expired`, `password_reset_token_used`, `password_current_incorrect`, `password_same_as_current`, `invalid_o_auth_state`, `o_auth_provider_error`, `o_auth_already_linked`, `provider_already_connected`, `o_auth_not_linked`, `cannot_unlink_only_auth`, `validation_failed`, `bad_request`, `ring_target_required`, `invalid_json`, `resource_not_found`, `not_found`, `forbidden`, `insufficient_permissions`, `connectors_consent_required`, `already_answered`, `expired`, `conflict`, `resource_already_exists`, `insufficient_balance`, `payment_required`, `subscription_required`, `feature_not_available`, `payment_failed`, `business_rule_violation`, `invalid_state_transition`, `unprocessable_entity`, `rate_limit_exceeded`, `queue_full`, `assistant_quota_exceeded`, `phone_purchase_rate_limited`, `user_phone_not_verified`, `account_not_verified`, `owner_verification_required`, `payment_method_required`, `trial_already_claimed`, `promotion_not_eligible`, `coupon_not_found`, `coupon_not_redeemable`, `coupon_already_redeemed`, `phone_number_not_active`, `phone_number_not_verified`, `phone_number_cannot_initiate_calls`, `flow_not_published`, `provider_call_rejected`, `concurrent_call_limit_exceeded`, `daily_call_limit_exceeded`, `contact_on_dnc_list`, `outside_callable_hours`, `call_already_completed`, `phone_provider_not_active`, `phone_number_already_connected`, `phone_number_not_connected`, `provider_must_be_sip`, `verification_only_for_sip`, `phone_verification_not_started`, `twilio_credentials_required`, `byoc_only`, `phone_already_registered`, `cannot_delete_system_provider`, `phone_number_type_unavailable`, `flow_name_already_exists`, `flow_structure_invalid`, `flow_has_connected_phones`, `flow_version_invalid`, `flow_version_conflict`, `flow_function_name_exists`, `flow_function_not_found`, `flow_generation_failed`, `payment_method_card_only`, `apple_transaction_invalid`, `apple_transaction_account_mismatch`, `sandbox_purchase_not_allowed`, `template_variable_resolution_failed`, `phone_number_in_use`, `phone_number_limit_reached`, `mfa_token_invalid`, `invalid_id_format`, `verification_code_invalid`, `cannot_delete_has_dependencies`, `in_use`, `unsupported_kind`, `offer_taken`, `offer_taken_self`, `offer_expired`, `already_taken`, `takeover_unsupported`, `schedule_not_found`, `schedule_already_paused`, `schedule_not_paused`, `invalid_cron_expression`, `invalid_timezone`, `campaign_not_found`, `campaign_not_draft`, `campaign_no_contacts`, `legal_acceptance_required`, `invitation_not_found`, `invitation_not_pending`, `invitation_expired`, `not_invitation_recipient`, `organization_suspended`, `already_organization_member`, `api_key_invalid`, `api_key_expired`, `api_key_revoked`, `api_key_not_allowed`, `api_key_insufficient_scope`, `api_key_ip_restricted`, `api_key_limit_reached`, `internal_error`, `service_error`, `service_unavailable`, `no_bots_available`, `region_saturated`, `recording_not_available`, `recording_service_not_configured`, `meta_not_configured`, `meta_page_already_connected`, `meta_form_already_mapped`, `meta_api_error`, `meta_lead_unrecoverable`, `unauthorized`
- `detail` (string, required) — Human-readable detail message for this specific error instance
- `status` (integer, required) — HTTP status code (mirrors the response status line)
- `title` (string, required) — Human-readable title for the error category
- `errors` (list of FieldError, optional, nullable) — Field-level validation errors, present when code is `validation_failed`
- `meta` (ErrorResponseMeta, optional, nullable) — Additional context metadata (e.g., retryAfterSecs for rate limits)
- `requestId` (string, optional, nullable) — Unique request identifier for debugging (also in X-Request-Id response header)

### 404 Not Found Error

`resource_not_found`

- `code` (enum, required) — Machine-readable error code for programmatic handling
  - Allowed values: `invalid_credentials`, `email_already_exists`, `phone_already_exists`, `contact_phone_already_exists`, `account_suspended`, `account_pending_deletion`, `login_pending_deletion`, `owns_organization_with_members`, `account_deletion_blocked`, `client_update_required`, `account_access_denied`, `token_expired`, `token_invalid`, `token_missing`, `account_header_missing`, `refresh_token_invalid`, `email_already_verified`, `email_verification_code_invalid`, `email_verification_code_expired`, `email_verification_code_used`, `email_service_unavailable`, `phone_already_verified`, `phone_verification_code_invalid`, `bot_check_failed`, `phone_verification_code_expired`, `phone_verification_code_used`, `phone_number_missing`, `email_not_verified`, `disposable_email_not_allowed`, `request_blocked`, `phone_verification_refused`, `sms_service_unavailable`, `mfa_already_enabled`, `mfa_not_enabled`, `mfa_not_setup`, `mfa_code_invalid`, `passkey_not_found`, `password_reset_token_invalid`, `password_reset_token_expired`, `password_reset_token_used`, `password_current_incorrect`, `password_same_as_current`, `invalid_o_auth_state`, `o_auth_provider_error`, `o_auth_already_linked`, `provider_already_connected`, `o_auth_not_linked`, `cannot_unlink_only_auth`, `validation_failed`, `bad_request`, `ring_target_required`, `invalid_json`, `resource_not_found`, `not_found`, `forbidden`, `insufficient_permissions`, `connectors_consent_required`, `already_answered`, `expired`, `conflict`, `resource_already_exists`, `insufficient_balance`, `payment_required`, `subscription_required`, `feature_not_available`, `payment_failed`, `business_rule_violation`, `invalid_state_transition`, `unprocessable_entity`, `rate_limit_exceeded`, `queue_full`, `assistant_quota_exceeded`, `phone_purchase_rate_limited`, `user_phone_not_verified`, `account_not_verified`, `owner_verification_required`, `payment_method_required`, `trial_already_claimed`, `promotion_not_eligible`, `coupon_not_found`, `coupon_not_redeemable`, `coupon_already_redeemed`, `phone_number_not_active`, `phone_number_not_verified`, `phone_number_cannot_initiate_calls`, `flow_not_published`, `provider_call_rejected`, `concurrent_call_limit_exceeded`, `daily_call_limit_exceeded`, `contact_on_dnc_list`, `outside_callable_hours`, `call_already_completed`, `phone_provider_not_active`, `phone_number_already_connected`, `phone_number_not_connected`, `provider_must_be_sip`, `verification_only_for_sip`, `phone_verification_not_started`, `twilio_credentials_required`, `byoc_only`, `phone_already_registered`, `cannot_delete_system_provider`, `phone_number_type_unavailable`, `flow_name_already_exists`, `flow_structure_invalid`, `flow_has_connected_phones`, `flow_version_invalid`, `flow_version_conflict`, `flow_function_name_exists`, `flow_function_not_found`, `flow_generation_failed`, `payment_method_card_only`, `apple_transaction_invalid`, `apple_transaction_account_mismatch`, `sandbox_purchase_not_allowed`, `template_variable_resolution_failed`, `phone_number_in_use`, `phone_number_limit_reached`, `mfa_token_invalid`, `invalid_id_format`, `verification_code_invalid`, `cannot_delete_has_dependencies`, `in_use`, `unsupported_kind`, `offer_taken`, `offer_taken_self`, `offer_expired`, `already_taken`, `takeover_unsupported`, `schedule_not_found`, `schedule_already_paused`, `schedule_not_paused`, `invalid_cron_expression`, `invalid_timezone`, `campaign_not_found`, `campaign_not_draft`, `campaign_no_contacts`, `legal_acceptance_required`, `invitation_not_found`, `invitation_not_pending`, `invitation_expired`, `not_invitation_recipient`, `organization_suspended`, `already_organization_member`, `api_key_invalid`, `api_key_expired`, `api_key_revoked`, `api_key_not_allowed`, `api_key_insufficient_scope`, `api_key_ip_restricted`, `api_key_limit_reached`, `internal_error`, `service_error`, `service_unavailable`, `no_bots_available`, `region_saturated`, `recording_not_available`, `recording_service_not_configured`, `meta_not_configured`, `meta_page_already_connected`, `meta_form_already_mapped`, `meta_api_error`, `meta_lead_unrecoverable`, `unauthorized`
- `detail` (string, required) — Human-readable detail message for this specific error instance
- `status` (integer, required) — HTTP status code (mirrors the response status line)
- `title` (string, required) — Human-readable title for the error category
- `errors` (list of FieldError, optional, nullable) — Field-level validation errors, present when code is `validation_failed`
- `meta` (ErrorResponseMeta, optional, nullable) — Additional context metadata (e.g., retryAfterSecs for rate limits)
- `requestId` (string, optional, nullable) — Unique request identifier for debugging (also in X-Request-Id response header)

### 429 Too Many Requests Error

Rate limit exceeded — retry after the delay in the response

- `code` (enum, required) — Machine-readable error code for programmatic handling
  - Allowed values: `invalid_credentials`, `email_already_exists`, `phone_already_exists`, `contact_phone_already_exists`, `account_suspended`, `account_pending_deletion`, `login_pending_deletion`, `owns_organization_with_members`, `account_deletion_blocked`, `client_update_required`, `account_access_denied`, `token_expired`, `token_invalid`, `token_missing`, `account_header_missing`, `refresh_token_invalid`, `email_already_verified`, `email_verification_code_invalid`, `email_verification_code_expired`, `email_verification_code_used`, `email_service_unavailable`, `phone_already_verified`, `phone_verification_code_invalid`, `bot_check_failed`, `phone_verification_code_expired`, `phone_verification_code_used`, `phone_number_missing`, `email_not_verified`, `disposable_email_not_allowed`, `request_blocked`, `phone_verification_refused`, `sms_service_unavailable`, `mfa_already_enabled`, `mfa_not_enabled`, `mfa_not_setup`, `mfa_code_invalid`, `passkey_not_found`, `password_reset_token_invalid`, `password_reset_token_expired`, `password_reset_token_used`, `password_current_incorrect`, `password_same_as_current`, `invalid_o_auth_state`, `o_auth_provider_error`, `o_auth_already_linked`, `provider_already_connected`, `o_auth_not_linked`, `cannot_unlink_only_auth`, `validation_failed`, `bad_request`, `ring_target_required`, `invalid_json`, `resource_not_found`, `not_found`, `forbidden`, `insufficient_permissions`, `connectors_consent_required`, `already_answered`, `expired`, `conflict`, `resource_already_exists`, `insufficient_balance`, `payment_required`, `subscription_required`, `feature_not_available`, `payment_failed`, `business_rule_violation`, `invalid_state_transition`, `unprocessable_entity`, `rate_limit_exceeded`, `queue_full`, `assistant_quota_exceeded`, `phone_purchase_rate_limited`, `user_phone_not_verified`, `account_not_verified`, `owner_verification_required`, `payment_method_required`, `trial_already_claimed`, `promotion_not_eligible`, `coupon_not_found`, `coupon_not_redeemable`, `coupon_already_redeemed`, `phone_number_not_active`, `phone_number_not_verified`, `phone_number_cannot_initiate_calls`, `flow_not_published`, `provider_call_rejected`, `concurrent_call_limit_exceeded`, `daily_call_limit_exceeded`, `contact_on_dnc_list`, `outside_callable_hours`, `call_already_completed`, `phone_provider_not_active`, `phone_number_already_connected`, `phone_number_not_connected`, `provider_must_be_sip`, `verification_only_for_sip`, `phone_verification_not_started`, `twilio_credentials_required`, `byoc_only`, `phone_already_registered`, `cannot_delete_system_provider`, `phone_number_type_unavailable`, `flow_name_already_exists`, `flow_structure_invalid`, `flow_has_connected_phones`, `flow_version_invalid`, `flow_version_conflict`, `flow_function_name_exists`, `flow_function_not_found`, `flow_generation_failed`, `payment_method_card_only`, `apple_transaction_invalid`, `apple_transaction_account_mismatch`, `sandbox_purchase_not_allowed`, `template_variable_resolution_failed`, `phone_number_in_use`, `phone_number_limit_reached`, `mfa_token_invalid`, `invalid_id_format`, `verification_code_invalid`, `cannot_delete_has_dependencies`, `in_use`, `unsupported_kind`, `offer_taken`, `offer_taken_self`, `offer_expired`, `already_taken`, `takeover_unsupported`, `schedule_not_found`, `schedule_already_paused`, `schedule_not_paused`, `invalid_cron_expression`, `invalid_timezone`, `campaign_not_found`, `campaign_not_draft`, `campaign_no_contacts`, `legal_acceptance_required`, `invitation_not_found`, `invitation_not_pending`, `invitation_expired`, `not_invitation_recipient`, `organization_suspended`, `already_organization_member`, `api_key_invalid`, `api_key_expired`, `api_key_revoked`, `api_key_not_allowed`, `api_key_insufficient_scope`, `api_key_ip_restricted`, `api_key_limit_reached`, `internal_error`, `service_error`, `service_unavailable`, `no_bots_available`, `region_saturated`, `recording_not_available`, `recording_service_not_configured`, `meta_not_configured`, `meta_page_already_connected`, `meta_form_already_mapped`, `meta_api_error`, `meta_lead_unrecoverable`, `unauthorized`
- `detail` (string, required) — Human-readable detail message for this specific error instance
- `status` (integer, required) — HTTP status code (mirrors the response status line)
- `title` (string, required) — Human-readable title for the error category
- `errors` (list of FieldError, optional, nullable) — Field-level validation errors, present when code is `validation_failed`
- `meta` (ErrorResponseMeta, optional, nullable) — Additional context metadata (e.g., retryAfterSecs for rate limits)
- `requestId` (string, optional, nullable) — Unique request identifier for debugging (also in X-Request-Id response header)

### 500 Internal Server Error

Internal server error — contact support with the requestId

- `code` (enum, required) — Machine-readable error code for programmatic handling
  - Allowed values: `invalid_credentials`, `email_already_exists`, `phone_already_exists`, `contact_phone_already_exists`, `account_suspended`, `account_pending_deletion`, `login_pending_deletion`, `owns_organization_with_members`, `account_deletion_blocked`, `client_update_required`, `account_access_denied`, `token_expired`, `token_invalid`, `token_missing`, `account_header_missing`, `refresh_token_invalid`, `email_already_verified`, `email_verification_code_invalid`, `email_verification_code_expired`, `email_verification_code_used`, `email_service_unavailable`, `phone_already_verified`, `phone_verification_code_invalid`, `bot_check_failed`, `phone_verification_code_expired`, `phone_verification_code_used`, `phone_number_missing`, `email_not_verified`, `disposable_email_not_allowed`, `request_blocked`, `phone_verification_refused`, `sms_service_unavailable`, `mfa_already_enabled`, `mfa_not_enabled`, `mfa_not_setup`, `mfa_code_invalid`, `passkey_not_found`, `password_reset_token_invalid`, `password_reset_token_expired`, `password_reset_token_used`, `password_current_incorrect`, `password_same_as_current`, `invalid_o_auth_state`, `o_auth_provider_error`, `o_auth_already_linked`, `provider_already_connected`, `o_auth_not_linked`, `cannot_unlink_only_auth`, `validation_failed`, `bad_request`, `ring_target_required`, `invalid_json`, `resource_not_found`, `not_found`, `forbidden`, `insufficient_permissions`, `connectors_consent_required`, `already_answered`, `expired`, `conflict`, `resource_already_exists`, `insufficient_balance`, `payment_required`, `subscription_required`, `feature_not_available`, `payment_failed`, `business_rule_violation`, `invalid_state_transition`, `unprocessable_entity`, `rate_limit_exceeded`, `queue_full`, `assistant_quota_exceeded`, `phone_purchase_rate_limited`, `user_phone_not_verified`, `account_not_verified`, `owner_verification_required`, `payment_method_required`, `trial_already_claimed`, `promotion_not_eligible`, `coupon_not_found`, `coupon_not_redeemable`, `coupon_already_redeemed`, `phone_number_not_active`, `phone_number_not_verified`, `phone_number_cannot_initiate_calls`, `flow_not_published`, `provider_call_rejected`, `concurrent_call_limit_exceeded`, `daily_call_limit_exceeded`, `contact_on_dnc_list`, `outside_callable_hours`, `call_already_completed`, `phone_provider_not_active`, `phone_number_already_connected`, `phone_number_not_connected`, `provider_must_be_sip`, `verification_only_for_sip`, `phone_verification_not_started`, `twilio_credentials_required`, `byoc_only`, `phone_already_registered`, `cannot_delete_system_provider`, `phone_number_type_unavailable`, `flow_name_already_exists`, `flow_structure_invalid`, `flow_has_connected_phones`, `flow_version_invalid`, `flow_version_conflict`, `flow_function_name_exists`, `flow_function_not_found`, `flow_generation_failed`, `payment_method_card_only`, `apple_transaction_invalid`, `apple_transaction_account_mismatch`, `sandbox_purchase_not_allowed`, `template_variable_resolution_failed`, `phone_number_in_use`, `phone_number_limit_reached`, `mfa_token_invalid`, `invalid_id_format`, `verification_code_invalid`, `cannot_delete_has_dependencies`, `in_use`, `unsupported_kind`, `offer_taken`, `offer_taken_self`, `offer_expired`, `already_taken`, `takeover_unsupported`, `schedule_not_found`, `schedule_already_paused`, `schedule_not_paused`, `invalid_cron_expression`, `invalid_timezone`, `campaign_not_found`, `campaign_not_draft`, `campaign_no_contacts`, `legal_acceptance_required`, `invitation_not_found`, `invitation_not_pending`, `invitation_expired`, `not_invitation_recipient`, `organization_suspended`, `already_organization_member`, `api_key_invalid`, `api_key_expired`, `api_key_revoked`, `api_key_not_allowed`, `api_key_insufficient_scope`, `api_key_ip_restricted`, `api_key_limit_reached`, `internal_error`, `service_error`, `service_unavailable`, `no_bots_available`, `region_saturated`, `recording_not_available`, `recording_service_not_configured`, `meta_not_configured`, `meta_page_already_connected`, `meta_form_already_mapped`, `meta_api_error`, `meta_lead_unrecoverable`, `unauthorized`
- `detail` (string, required) — Human-readable detail message for this specific error instance
- `status` (integer, required) — HTTP status code (mirrors the response status line)
- `title` (string, required) — Human-readable title for the error category
- `errors` (list of FieldError, optional, nullable) — Field-level validation errors, present when code is `validation_failed`
- `meta` (ErrorResponseMeta, optional, nullable) — Additional context metadata (e.g., retryAfterSecs for rate limits)
- `requestId` (string, optional, nullable) — Unique request identifier for debugging (also in X-Request-Id response header)

## Types

### PhoneNumberUsageCampaign

Campaign that dials from a phone number

- `id` (string, required) — Campaign ID
- `name` (string, required) — Campaign name
- `status` (enum, required) — Campaign status
  - Allowed values: `draft`, `pending`, `running`, `draining`, `paused`, `completed`, `canceled`

### PhoneNumberUsageMetaLeadForm

Meta lead form mapping that uses a phone number as caller ID

- `enabled` (boolean, required) — Whether new leads from this form are called
- `formId` (string, required) — Meta lead form ID
- `integrationId` (string, required) — Meta integration (Facebook Page connection) the mapping belongs to
- `mappingId` (string, required) — Form mapping ID
- `pageConnected` (boolean, required) — `false` once the Facebook Page was disconnected. The mapping still holds the number until it is deleted.
- `pageName` (string, required) — Facebook Page name
- `formName` (string, optional, nullable) — Lead form name

### PhoneNumberUsageSchedule

Call schedule that dials from a phone number

- `id` (string, required) — Schedule ID
- `name` (string, required) — Schedule name
- `status` (enum, required) — Schedule status
  - Allowed values: `active`, `paused`, `completed`, `canceled`

### PhoneNumberUsageFlow

Flow connected to a phone number for inbound calls

- `id` (string, required) — Flow ID
- `name` (string, required) — Flow name

### FieldError

Individual field error for validation responses Appears in the `errors[]` array when `code` is `validation_failed` # Example ```json { "field": "email", "code": "invalid_format", "message": "Email format is invalid" } ```

- `code` (string, required) — Specific error code for this field
- `field` (string, required) — The field name that failed validation
- `message` (string, required) — Human-readable error message

### ErrorResponseMeta

Additional context metadata (e.g., retryAfterSecs for rate limits)

## Examples

**Response**

```json
{
  "campaigns": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "October follow-up",
      "status": "draft"
    }
  ],
  "canRelease": false,
  "metaLeadForms": [
    {
      "enabled": true,
      "formId": "1234567890123456",
      "integrationId": "550e8400-e29b-41d4-a716-446655440000",
      "mappingId": "550e8400-e29b-41d4-a716-446655440000",
      "pageConnected": true,
      "pageName": "Talkif",
      "formName": "Spring campaign"
    }
  ],
  "phoneNumberId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "schedules": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Weekly check-in",
      "status": "active"
    }
  ],
  "inboundFlow": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Receptionist"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.talkif.ai/api/v1/phone/numbers/id/usage"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.talkif.ai/api/v1/phone/numbers/id/usage';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.talkif.ai/api/v1/phone/numbers/id/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.talkif.ai/api/v1/phone/numbers/id/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.talkif.ai/api/v1/phone/numbers/id/usage")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.talkif.ai/api/v1/phone/numbers/id/usage', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.talkif.ai/api/v1/phone/numbers/id/usage");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.talkif.ai/api/v1/phone/numbers/id/usage")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```