Installation
go get github.com/team-telnyx/telnyx-go
Setup
import (
"context"
"fmt"
"os"
"github.com/team-telnyx/telnyx-go" "github.com/team-telnyx/telnyx-go/option" )
client := telnyx.NewClient( option.WithAPIKey(os.Getenv("TELNYX_API_KEY")), )
All examples below assume `client` is already initialized as shown above.
## Error Handling
All API calls can fail with network errors, rate limits (429), validation errors (422),
or authentication errors (401). Always handle errors in production code:
```go
import "errors"
result, err := client.Messages.Send(ctx, params)
if err != nil {
var apiErr *telnyx.Error
if errors.As(err, &apiErr) {
switch apiErr.StatusCode {
case 422:
fmt.Println("Validation error — check required fields and formats")
case 429:
// Rate limited — wait and retry with exponential backoff
fmt.Println("Rate limited, retrying...")
default:
fmt.Printf("API error %d: %s\n", apiErr.StatusCode, apiErr.Error())
}
} else {
fmt.Println("Network error — check connectivity and retry")
}
}
Common error codes: 401 invalid API key, 403 insufficient permissions,
404 resource not found, 422 validation error (check field formats),
429 rate limited (retry with exponential backoff).
Important Notes
- Phone numbers must be in E.164 format (e.g.,
+13125550001). Include the+prefix and country code. No spaces, dashes, or parentheses. - Pagination: Use
ListAutoPaging()for automatic iteration:iter := client.Resource.ListAutoPaging(ctx, params); for iter.Next() { item := iter.Current() }.
Retrieve Bundles
Get all allowed bundles.
GET /bundle_pricing/billing_bundles
page, err := client.BundlePricing.BillingBundles.List(context.Background(), telnyx.BundlePricingBillingBundleListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: cost_code (string), created_at (date), currency (string), id (uuid), is_public (boolean), mrc_price (float), name (string), slug (string), specs (array[string])
Get Bundle By Id
Get a single bundle by ID.
GET /bundle_pricing/billing_bundles/{bundle_id}
billingBundle, err := client.BundlePricing.BillingBundles.Get(
context.Background(),
"8661948c-a386-4385-837f-af00f40f111a",
telnyx.BundlePricingBillingBundleGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", billingBundle.Data)
Returns: active (boolean), bundle_limits (array[object]), cost_code (string), created_at (date), id (uuid), is_public (boolean), name (string), slug (string)
Get User Bundles
Get a paginated list of user bundles.
GET /bundle_pricing/user_bundles
page, err := client.BundlePricing.UserBundles.List(context.Background(), telnyx.BundlePricingUserBundleListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: active (boolean), billing_bundle (object), created_at (date), id (uuid), resources (array[object]), updated_at (date), user_id (uuid)
Create User Bundles
Creates multiple user bundles for the user.
POST /bundle_pricing/user_bundles/bulk
Optional: idempotency_key (uuid), items (array[object])
userBundle, err := client.BundlePricing.UserBundles.New(context.Background(), telnyx.BundlePricingUserBundleNewParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", userBundle.Data)
Returns: active (boolean), billing_bundle (object), created_at (date), id (uuid), resources (array[object]), updated_at (date), user_id (uuid)
Get Unused User Bundles
Returns all user bundles that aren't in use.
GET /bundle_pricing/user_bundles/unused
response, err := client.BundlePricing.UserBundles.ListUnused(context.Background(), telnyx.BundlePricingUserBundleListUnusedParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: billing_bundle (object), user_bundle_ids (array[string])
Get User Bundle by Id
Retrieves a user bundle by its ID.
GET /bundle_pricing/user_bundles/{user_bundle_id}
userBundle, err := client.BundlePricing.UserBundles.Get(
context.Background(),
"ca1d2263-d1f1-43ac-ba53-248e7a4bb26a",
telnyx.BundlePricingUserBundleGetParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", userBundle.Data)
Returns: active (boolean), billing_bundle (object), created_at (date), id (uuid), resources (array[object]), updated_at (date), user_id (uuid)
Deactivate User Bundle
Deactivates a user bundle by its ID.
DELETE /bundle_pricing/user_bundles/{user_bundle_id}
response, err := client.BundlePricing.UserBundles.Deactivate(
context.Background(),
"ca1d2263-d1f1-43ac-ba53-248e7a4bb26a",
telnyx.BundlePricingUserBundleDeactivateParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: active (boolean), billing_bundle (object), created_at (date), id (uuid), resources (array[object]), updated_at (date), user_id (uuid)
Get User Bundle Resources
Retrieves the resources of a user bundle by its ID.
GET /bundle_pricing/user_bundles/{user_bundle_id}/resources
response, err := client.BundlePricing.UserBundles.ListResources(
context.Background(),
"ca1d2263-d1f1-43ac-ba53-248e7a4bb26a",
telnyx.BundlePricingUserBundleListResourcesParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: created_at (date), id (uuid), resource (string), resource_type (string), updated_at (date)
List all document links
List all documents links ordered by created_at descending.
GET /document_links
page, err := client.DocumentLinks.List(context.Background(), telnyx.DocumentLinkListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: created_at (string), document_id (uuid), id (uuid), linked_record_type (string), linked_resource_id (string), record_type (string), updated_at (string)
List all documents
List all documents ordered by created_at descending.
GET /documents
page, err := client.Documents.List(context.Background(), telnyx.DocumentListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
Upload a document
Upload a document. Uploaded files must be linked to a service within 30 minutes or they will be automatically deleted.
POST /documents
Optional: customer_reference (string), file (byte), filename (string), url (string)
response, err := client.Documents.UploadJson(context.Background(), telnyx.DocumentUploadJsonParams{
Document: telnyx.DocumentUploadJsonParamsDocument{},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
Retrieve a document
Retrieve a document.
GET /documents/{id}
document, err := client.Documents.Get(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", document.Data)
Returns: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
Update a document
Update a document.
PATCH /documents/{id}
Optional: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
document, err := client.Documents.Update(
context.Background(),
"6a09cdc3-8948-47f0-aa62-74ac943d6c58",
telnyx.DocumentUpdateParams{
DocServiceDocument: telnyx.DocServiceDocumentParam{},
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", document.Data)
Returns: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
Delete a document
Delete a document. A document can only be deleted if it's not linked to a service. If it is linked to a service, it must be unlinked prior to deleting.
DELETE /documents/{id}
document, err := client.Documents.Delete(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", document.Data)
Returns: av_scan_status (enum: scanned, infected, pending_scan, not_scanned), content_type (string), created_at (string), customer_reference (string), filename (string), id (uuid), record_type (string), sha256 (string), size (object), status (enum: pending, verified, denied), updated_at (string)
Download a document
Download a document.
GET /documents/{id}/download
response, err := client.Documents.Download(context.Background(), "6a09cdc3-8948-47f0-aa62-74ac943d6c58")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response)
Generate a temporary download link for a document
Generates a temporary pre-signed URL that can be used to download the document directly from the storage backend without authentication.
GET /documents/{id}/download_link
response, err := client.Documents.GenerateDownloadLink(context.Background(), "550e8400-e29b-41d4-a716-446655440000")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: url (uri)
Update requirement group for a phone number order
POST /number_order_phone_numbers/{id}/requirement_group — Required: requirement_group_id
response, err := client.NumberOrderPhoneNumbers.UpdateRequirementGroup(
context.Background(),
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
telnyx.NumberOrderPhoneNumberUpdateRequirementGroupParams{
RequirementGroupID: "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: bundle_id (uuid), country_code (string), deadline (date-time), id (uuid), is_block_number (boolean), locality (string), order_request_id (uuid), phone_number (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), requirements_met (boolean), requirements_status (string), status (string), sub_number_order_id (uuid)
Retrieve regulatory requirements for a list of phone numbers
GET /phone_numbers_regulatory_requirements
phoneNumbersRegulatoryRequirement, err := client.PhoneNumbersRegulatoryRequirements.Get(context.Background(), telnyx.PhoneNumbersRegulatoryRequirementGetParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", phoneNumbersRegulatoryRequirement.Data)
Returns: phone_number (string), phone_number_type (string), record_type (string), region_information (array[object]), regulatory_requirements (array[object])
Retrieve regulatory requirements
GET /regulatory_requirements
regulatoryRequirement, err := client.RegulatoryRequirements.Get(context.Background(), telnyx.RegulatoryRequirementGetParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", regulatoryRequirement.Data)
Returns: action (string), country_code (string), phone_number_type (string), regulatory_requirements (array[object])
List requirement groups
GET /requirement_groups
requirementGroups, err := client.RequirementGroups.List(context.Background(), telnyx.RequirementGroupListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroups)
Create a new requirement group
POST /requirement_groups — Required: country_code, phone_number_type, action
Optional: customer_reference (string), regulatory_requirements (array[object])
requirementGroup, err := client.RequirementGroups.New(context.Background(), telnyx.RequirementGroupNewParams{
Action: telnyx.RequirementGroupNewParamsActionOrdering,
CountryCode: "US",
PhoneNumberType: telnyx.RequirementGroupNewParamsPhoneNumberTypeLocal,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroup.ID)
Returns: action (string), country_code (string), created_at (date-time), customer_reference (string), id (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), status (enum: approved, unapproved, pending-approval, declined, expired), updated_at (date-time)
Get a single requirement group by ID
GET /requirement_groups/{id}
requirementGroup, err := client.RequirementGroups.Get(context.Background(), "id")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroup.ID)
Returns: action (string), country_code (string), created_at (date-time), customer_reference (string), id (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), status (enum: approved, unapproved, pending-approval, declined, expired), updated_at (date-time)
Update requirement values in requirement group
PATCH /requirement_groups/{id}
Optional: customer_reference (string), regulatory_requirements (array[object])
requirementGroup, err := client.RequirementGroups.Update(
context.Background(),
"id",
telnyx.RequirementGroupUpdateParams{},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroup.ID)
Returns: action (string), country_code (string), created_at (date-time), customer_reference (string), id (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), status (enum: approved, unapproved, pending-approval, declined, expired), updated_at (date-time)
Delete a requirement group by ID
DELETE /requirement_groups/{id}
requirementGroup, err := client.RequirementGroups.Delete(context.Background(), "id")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroup.ID)
Returns: action (string), country_code (string), created_at (date-time), customer_reference (string), id (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), status (enum: approved, unapproved, pending-approval, declined, expired), updated_at (date-time)
Submit a Requirement Group for Approval
POST /requirement_groups/{id}/submit_for_approval
requirementGroup, err := client.RequirementGroups.SubmitForApproval(context.Background(), "id")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementGroup.ID)
Returns: action (string), country_code (string), created_at (date-time), customer_reference (string), id (string), phone_number_type (string), record_type (string), regulatory_requirements (array[object]), status (enum: approved, unapproved, pending-approval, declined, expired), updated_at (date-time)
List all requirement types
List all requirement types ordered by created_at descending
GET /requirement_types
requirementTypes, err := client.RequirementTypes.List(context.Background(), telnyx.RequirementTypeListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementTypes.Data)
Returns: acceptance_criteria (object), created_at (string), description (string), example (string), id (uuid), name (string), record_type (string), type (enum: document, address, textual), updated_at (string)
Retrieve a requirement types
Retrieve a requirement type by id
GET /requirement_types/{id}
requirementType, err := client.RequirementTypes.Get(context.Background(), "a38c217a-8019-48f8-bff6-0fdd9939075b")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirementType.Data)
Returns: acceptance_criteria (object), created_at (string), description (string), example (string), id (uuid), name (string), record_type (string), type (enum: document, address, textual), updated_at (string)
List all requirements
List all requirements with filtering, sorting, and pagination
GET /requirements
page, err := client.Requirements.List(context.Background(), telnyx.RequirementListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: action (enum: both, branded_calling, ordering, porting), country_code (string), created_at (string), id (uuid), locality (string), phone_number_type (enum: local, national, toll_free), record_type (string), requirements_types (array[object]), updated_at (string)
Retrieve a document requirement
Retrieve a document requirement record
GET /requirements/{id}
requirement, err := client.Requirements.Get(context.Background(), "a9dad8d5-fdbd-49d7-aa23-39bb08a5ebaa")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", requirement.Data)
Returns: action (enum: both, branded_calling, ordering, porting), country_code (string), created_at (string), id (uuid), locality (string), phone_number_type (enum: local, national, toll_free), record_type (string), requirements_types (array[object]), updated_at (string)
Update requirement group for a sub number order
POST /sub_number_orders/{id}/requirement_group — Required: requirement_group_id
response, err := client.SubNumberOrders.UpdateRequirementGroup(
context.Background(),
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
telnyx.SubNumberOrderUpdateRequirementGroupParams{
RequirementGroupID: "a4b201f9-8646-4e54-a7d2-b2e403eeaf8c",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", response.Data)
Returns: country_code (string), created_at (date-time), customer_reference (string), id (uuid), is_block_sub_number_order (boolean), order_request_id (uuid), phone_number_type (string), phone_numbers (array[object]), phone_numbers_count (integer), record_type (string), regulatory_requirements (array[object]), requirements_met (boolean), status (string), updated_at (date-time)
List all user addresses
Returns a list of your user addresses.
GET /user_addresses
page, err := client.UserAddresses.List(context.Background(), telnyx.UserAddressListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (uuid), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string)
Creates a user address
Creates a user address.
POST /user_addresses — Required: first_name, last_name, business_name, street_address, locality, country_code
Optional: administrative_area (string), borough (string), customer_reference (string), extended_address (string), neighborhood (string), phone_number (string), postal_code (string), skip_address_verification (boolean)
userAddress, err := client.UserAddresses.New(context.Background(), telnyx.UserAddressNewParams{
BusinessName: "Toy-O'Kon",
CountryCode: "US",
FirstName: "Alfred",
LastName: "Foster",
Locality: "Austin",
StreetAddress: "600 Congress Avenue",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", userAddress.Data)
Returns: administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (uuid), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string)
Retrieve a user address
Retrieves the details of an existing user address.
GET /user_addresses/{id}
userAddress, err := client.UserAddresses.Get(context.Background(), "id")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", userAddress.Data)
Returns: administrative_area (string), borough (string), business_name (string), country_code (string), created_at (string), customer_reference (string), extended_address (string), first_name (string), id (uuid), last_name (string), locality (string), neighborhood (string), phone_number (string), postal_code (string), record_type (string), street_address (string), updated_at (string)
List all Verified Numbers
Gets a paginated list of Verified Numbers.
GET /verified_numbers
page, err := client.VerifiedNumbers.List(context.Background(), telnyx.VerifiedNumberListParams{})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", page)
Returns: phone_number (string), record_type (enum: verified_number), verified_at (string)
Request phone number verification
Initiates phone number verification procedure. Supports DTMF extension dialing for voice calls to numbers behind IVR systems.
POST /verified_numbers — Required: phone_number, verification_method
Optional: extension (string)
verifiedNumber, err := client.VerifiedNumbers.New(context.Background(), telnyx.VerifiedNumberNewParams{
PhoneNumber: "+15551234567",
VerificationMethod: telnyx.VerifiedNumberNewParamsVerificationMethodSMS,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", verifiedNumber.PhoneNumber)
Returns: phone_number (string), verification_method (string)
Retrieve a verified number
GET /verified_numbers/{phone_number}
verifiedNumberDataWrapper, err := client.VerifiedNumbers.Get(context.Background(), "+15551234567")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", verifiedNumberDataWrapper.Data)
Returns: phone_number (string), record_type (enum: verified_number), verified_at (string)
Delete a verified number
DELETE /verified_numbers/{phone_number}
verifiedNumberDataWrapper, err := client.VerifiedNumbers.Delete(context.Background(), "+15551234567")
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", verifiedNumberDataWrapper.Data)
Returns: phone_number (string), record_type (enum: verified_number), verified_at (string)
Submit verification code
POST /verified_numbers/{phone_number}/actions/verify — Required: verification_code
verifiedNumberDataWrapper, err := client.VerifiedNumbers.Actions.SubmitVerificationCode(
context.Background(),
"+15551234567",
telnyx.VerifiedNumberActionSubmitVerificationCodeParams{
VerificationCode: "123456",
},
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%+v\n", verifiedNumberDataWrapper.Data)
Returns: phone_number (string), record_type (enum: verified_number), verified_at (string)