Agent Skill · Sinch

sinch-numbers-api

Search, rent, manage, and release phone numbers with the Sinch Numbers API. Use when listing active numbers, searching available numbers, renting or releasing numbers, updating number configuration (SMS/voice/callback), managing emergency addresses, or checking available regions.

View SKILL.md on GitHub → Source repository Provider profile
Provider: Sinch Path in repo: skills/sinch-numbers-api/SKILL.md

Skill body

Sinch Numbers API

Overview

The Numbers API lets you search, activate, manage, and release phone numbers — the prerequisite for SMS, Voice, and Conversation APIs.

Agent Instructions

Before generating code, gather from the user (skip any item already specified in the prompt or context):

  1. Approach — SDK or direct API calls (curl/fetch/requests)? Default to SDK if @sinch/sdk-core (Node), sinch (Python), or com.sinch.sdk (Java) is already present in the project.
  2. Language — for SDK: Node.js, Python, Java, or .NET. For direct API: any language, or curl.

When the user chooses SDK, refer to the sinch-sdks skill for installation and client initialization, then to the bundled language references and SDK reference linked in Links.

When the user chooses direct API calls, refer to the Numbers API Reference linked in Links for request/response schemas.

Security: See the Security section below for url fetching policy, handling inbound callback content, and credential handling.

Getting Started

Authentication

See sinch-authentication for full setup.

Verify connectivity

curl -X GET \
  "https://numbers.api.sinch.com/v1/projects/$SINCH_PROJECT_ID/activeNumbers?regionCode=US&type=LOCAL&pageSize=10" \
  -H "Authorization: Bearer $SINCH_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

A 200 response confirms credentials and project access.

Key Concepts

Workflows

Search and rent a number

  1. GET /availableRegions — discover valid regionCode values
  2. GET /availableNumbers?regionCode={code}&type={type} — search (both params required)
  3. Pick a number → POST /availableNumbers/{phoneNumber}:rent with config body
  4. GET /activeNumbers/{phoneNumber} — confirm activation

Use POST /availableNumbers:rentAny to skip step 3 (US LOCAL numbers only).

Safe retries for billable operations

Before retrying any potentially billable action (for example :rent, :rentAny, or :release) after an incomplete/uncertain response:

  1. Check current state first using a read endpoint (GET /activeNumbers/{phoneNumber} or GET /activeNumbers with filters)
  2. Retry only if the verification shows the prior action did not succeed
  3. If state is ambiguous, prefer listing active numbers and matching on phoneNumber before issuing another billable request

Update number configuration

  1. GET /activeNumbers/{phoneNumber} — check current config
  2. PATCH /activeNumbers/{phoneNumber} — set displayName, smsConfiguration, or voiceConfiguration
  3. To unlink, send empty string "" in servicePlanId or campaignId

Release a number

POST /activeNumbers/{phoneNumber}:release

Fetch all numbers to JSON

Run node scripts/get_numbers.cjs --output numbers.json (uses SINCH_PROJECT_ID, SINCH_KEY_ID, SINCH_KEY_SECRET env vars). Supports --region and --type filters.

Emergency addresses

Use the emergency address endpoints on active numbers: GET, provision, deprovision, validate. See API reference.

Number orders (KYC-regulated regions)

Use the numberOrders endpoints: lookupNumberRequirements → createNumberOrder → upload registration/attachments → submit. See API reference.

Imported numbers

A separate API at https://imported.numbers.api.sinch.com handles importing non-Sinch numbers (DCA) and hosting orders. See API reference.

Gotchas

Security

Skill frontmatter

metadata: {"author" => "Sinch", "version" => "1.1.3", "category" => "Numbers", "tags" => "numbers, phone-numbers, rent, release, search, sms, voice, configuration", "uses" => ["sinch-authentication", "sinch-sdks"]}