Class: Telnyx::Resources::Dir

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/dir.rb,
lib/telnyx/resources/dir/comments.rb,
lib/telnyx/resources/dir/references.rb,
lib/telnyx/resources/dir/verify_email.rb,
lib/telnyx/resources/dir/phone_numbers.rb,
lib/telnyx/resources/dir/phone_number_batches.rb,
sig/telnyx/resources/dir.rbs,
sig/telnyx/resources/dir/comments.rbs,
sig/telnyx/resources/dir/references.rbs,
sig/telnyx/resources/dir/verify_email.rbs,
sig/telnyx/resources/dir/phone_numbers.rbs,
sig/telnyx/resources/dir/phone_number_batches.rbs

Defined Under Namespace

Classes: Comments, PhoneNumberBatches, PhoneNumbers, References, VerifyEmail

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Dir

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Dir.

Parameters:



363
364
365
366
367
368
369
370
 
# File 'lib/telnyx/resources/dir.rb', line 363

def initialize(client:)
  @client = client
  @comments = Telnyx::Resources::Dir::Comments.new(client: client)
  @phone_number_batches = Telnyx::Resources::Dir::PhoneNumberBatches.new(client: client)
  @phone_numbers = Telnyx::Resources::Dir::PhoneNumbers.new(client: client)
  @references = Telnyx::Resources::Dir::References.new(client: client)
  @verify_email = Telnyx::Resources::Dir::VerifyEmail.new(client: client)
end

Instance Attribute Details

#comments ⇒ Telnyx::Resources::Dir::Comments (readonly)

Read messages from the Telnyx vetting team and reply with clarifying information.

Returns:



9
10
11
 
# File 'lib/telnyx/resources/dir.rb', line 9

def comments
  @comments
end

#phone_number_batches ⇒ Telnyx::Resources::Dir::PhoneNumberBatches (readonly)

Phone numbers are submitted to Telnyx for vetting in batches. Batches group all numbers added in a single request under the same Letter of Authorization.

Returns:



14
15
16
 
# File 'lib/telnyx/resources/dir.rb', line 14

def phone_number_batches
  @phone_number_batches
end

#phone_numbers ⇒ Telnyx::Resources::Dir::PhoneNumbers (readonly)

Associate phone numbers with a verified DIR so calls from those numbers carry the DIR's display identity.

Returns:



19
20
21
 
# File 'lib/telnyx/resources/dir.rb', line 19

def phone_numbers
  @phone_numbers
end

#references ⇒ Telnyx::Resources::Dir::References (readonly)

Submit and manage the two business references and one financial reference that vouch for a DIR. References are contacted to confirm the business identity during vetting.

Returns:



25
26
27
 
# File 'lib/telnyx/resources/dir.rb', line 25

def references
  @references
end

#verify_email ⇒ Telnyx::Resources::Dir::VerifyEmail (readonly)

Verify ownership of a DIR's authorizer email. A short code is emailed and confirmed; the email must be verified before references can be submitted.

Returns:



30
31
32
 
# File 'lib/telnyx/resources/dir.rb', line 30

def verify_email
  @verify_email
end

Instance Method Details

#delete(dir_id, request_options: {}) ⇒ nil

Delete a DIR. Failure modes: 400 if a child phone number is in a non-deletable status, 409 if the DIR has an unresolved infringement claim, 404 if the DIR is not yours.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)
  • request_options: (Telnyx::request_opts)

Returns:

  • (nil)

See Also:



178
179
180
181
182
183
184
185
 
# File 'lib/telnyx/resources/dir.rb', line 178

def delete(dir_id, params = {})
  @client.request(
    method: :delete,
    path: ["dir/%1$s", dir_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#list(filter_call_reason_contains: nil, filter_display_name_contains: nil, filter_enterprise_id: nil, filter_expiring_at_gte: nil, filter_expiring_at_lte: nil, filter_status: nil, page_number: nil, page_size: nil, sort: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::DirAPI>

Some parameter documentations has been truncated, see Models::DirListParams for more details.

Returns every DIR (Display Identity Record) you own, across all of your enterprises, as a single list. Pagination is JSON:API style (page[number], page[size], max 250). Supports filter[] query params: filter[enterprise_id], filter[status], filter[display_name][contains], filter[call_reason][contains], plus the renewal-window filters filter[expiring_at][gte] / filter[expiring_at][lte]. Sortable by created_at, updated_at, display_name, status (prefix - for descending; default -created_at).

Parameters:

  • filter_call_reason_contains (String) —

    Case-insensitive partial match on call reason.

  • filter_display_name_contains (String) —

    Case-insensitive partial match on display name.

  • filter_enterprise_id (String) —

    Filter by enterprise ID.

  • filter_expiring_at_gte (Time) —

    Return only DIRs whose expiring_at is at or after this ISO-8601 timestamp. Pai

  • filter_expiring_at_lte (Time) —

    Return only DIRs whose expiring_at is at or before this ISO-8601 timestamp.

  • filter_status (Symbol, Telnyx::Models::DirStatus) —

    Filter by DIR status.

  • page_number (Integer) —

    1-based page number. Out-of-range values return an empty page with correct meta.

  • page_size (Integer) —

    Items per page. Maximum 250; values above are clamped to 250.

  • sort (Symbol, Telnyx::Models::DirListParams::Sort) —

    Sort field. Allowed values: created_at, updated_at, display_name, status

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/telnyx/resources/dir.rb', line 143

def list(params = {})
  parsed, options = Telnyx::DirListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "dir",
    query: query.transform_keys(
      filter_call_reason_contains: "filter[call_reason][contains]",
      filter_display_name_contains: "filter[display_name][contains]",
      filter_enterprise_id: "filter[enterprise_id]",
      filter_expiring_at_gte: "filter[expiring_at][gte]",
      filter_expiring_at_lte: "filter[expiring_at][lte]",
      filter_status: "filter[status]",
      page_number: "page[number]",
      page_size: "page[size]"
    ),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::DirAPI,
    options: options
  )
end

#list_document_types(request_options: {}) ⇒ Telnyx::Models::DirListDocumentTypesResponse

Reference list of document_type values accepted by DirCreateRequest.documents[].document_type and the infringement-contest endpoint. Each entry has a stable short_name (used in API calls) and a customer-facing description.

Parameters:

Returns:

See Also:



199
200
201
202
203
204
205
206
 
# File 'lib/telnyx/resources/dir.rb', line 199

def list_document_types(params = {})
  @client.request(
    method: :get,
    path: "dir/document_types",
    model: Telnyx::Models::DirListDocumentTypesResponse,
    options: params[:request_options]
  )
end

#list_infringement_claims(dir_id, page_number: nil, page_size: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::InfringementClaim>

Some parameter documentations has been truncated, see Models::DirListInfringementClaimsParams for more details.

Return the trademark or copyright claims filed against this DIR. Each claim's status is pending (newly filed; DIR auto-suspended), contested (you have submitted contest evidence; awaiting resolution), or resolved (final). Resolution outcomes: upheld (claim accepted; DIR stays suspended/permanently_rejected), rejected (claim dismissed; DIR restored to verified), modified (partial outcome).

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • page_number (Integer) —

    1-based page number. Out-of-range values return an empty page with correct meta.

  • page_size (Integer) —

    Items per page. Maximum 250; values above are clamped to 250.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/telnyx/resources/dir.rb', line 231

def list_infringement_claims(dir_id, params = {})
  parsed, options = Telnyx::DirListInfringementClaimsParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["dir/%1$s/infringement_claims", dir_id],
    query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::InfringementClaim,
    options: options
  )
end

#new_loa(dir_id, phone_numbers:, agent: nil, signature: nil, request_options: {}) ⇒ StringIO

Some parameter documentations has been truncated, see Models::DirNewLoaParams for more details.

Generate a pre-filled Letter of Authorization (LOA) PDF for a DIR. Enterprise identity (legal name, DBA, address, contact, website, tax id) and the DIR display name are read server-side; the caller supplies the telephone numbers to authorize, an optional Authorized Agent block, and an optional drawn signature.

When signature is omitted the PDF is returned unsigned so the customer can sign it externally and upload it via the Documents API. When signature is present the PDF embeds the supplied image, printed name, and signed-at date.

Returns application/pdf.

Parameters:

Returns:

  • (StringIO)

See Also:



273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/telnyx/resources/dir.rb', line 273

def new_loa(dir_id, params)
  parsed, options = Telnyx::DirNewLoaParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["dir/%1$s/loa", dir_id],
    headers: {"accept" => "application/pdf"},
    body: parsed,
    model: StringIO,
    options: options
  )
end

#retrieve(dir_id, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Returns a single DIR by id. The enterprise is resolved server-side from the DIR id. Returns 404 if the DIR does not exist or is not yours.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



44
45
46
47
48
49
50
51
 
# File 'lib/telnyx/resources/dir.rb', line 44

def retrieve(dir_id, params = {})
  @client.request(
    method: :get,
    path: ["dir/%1$s", dir_id],
    model: Telnyx::DirWrapped,
    options: params[:request_options]
  )
end

#submit(dir_id, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Submit a DIR for vetting. Sends the DIR back through the vetting cycle from any non-terminal status. When re-submitting from suspended or expired, the DIR's previous Branded Calling registration is torn down transactionally and its phone numbers flip back to submitted. When re-submitting from verified, the existing registration stays live throughout the new vetting cycle.

Returns 400 from submitted/in_review/permanently_rejected. Returns 409 if the DIR has an unresolved infringement claim.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



303
304
305
306
307
308
309
310
 
# File 'lib/telnyx/resources/dir.rb', line 303

def submit(dir_id, params = {})
  @client.request(
    method: :post,
    path: ["dir/%1$s/submit", dir_id],
    model: Telnyx::DirWrapped,
    options: params[:request_options]
  )
end

#update(dir_id, authorizer_email: nil, authorizer_name: nil, call_reasons: nil, certify_brand_is_accurate: nil, certify_ip_ownership: nil, certify_no_shaft_content: nil, display_name: nil, documents: nil, logo_url: nil, reselling: nil, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Some parameter documentations has been truncated, see Models::DirUpdateParams for more details.

Edit a DIR. DIRs in draft, rejected, unsuccessful, or suspended can be edited freely: PATCH is a pure edit, status is never changed, and you re-vet by calling POST /v2/dir/{dir_id}/submit explicitly. A verified DIR can also be edited in place: a PATCH that changes any value returns the DIR to draft and branded delivery stops until you re-submit and the DIR is approved again, while a PATCH that changes nothing (an empty body or values identical to the current ones) leaves the DIR verified, so idempotent retries are safe. DIRs in any other status (submitted, in_review, expired, infringement_claimed, permanently_rejected) cannot be edited.

Parameters:

  • dir_id (String) —

    The DIR id. Lowercase UUID.

  • authorizer_email (String) —

    Contact email of the authorizer. Telnyx may send verification or infringement no

  • authorizer_name (String) —

    Name of the person at your enterprise authorizing this DIR. Must be a real indiv

  • call_reasons (Array<String>) —

    1–10 reasons your business calls customers. Validate phrasing against `POST /cal

  • certify_brand_is_accurate (Boolean) —

    Certification that the DIR information is accurate. Must be true for the DIR t

  • certify_ip_ownership (Boolean) —

    Certification of ownership of any logos/trademarks shown. Must be true for the

  • certify_no_shaft_content (Boolean) —

    Certification that this DIR is not used for SHAFT content (Sex, Hate, Alcohol, F

  • display_name (String) —

    Name shown to call recipients. 1–35 characters, no emoji, not whitespace-only.

  • documents (Array<Telnyx::Models::Document>) —

    Additional supporting documents to attach. Append-only: existing documents are n

  • logo_url (String) —

    Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).

  • reselling (Boolean) —

    Set to true if your organization places calls on behalf of other enterprises (BP

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/telnyx/resources/dir.rb', line 95

def update(dir_id, params = {})
  parsed, options = Telnyx::DirUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["dir/%1$s", dir_id],
    body: parsed,
    model: Telnyx::DirWrapped,
    options: options
  )
end

#update_infringement(dir_id, certify_brand_is_accurate:, certify_ip_ownership:, certify_no_infringement:, certify_no_shaft_content:, infringement_resolution_notes:, call_reasons: nil, display_name: nil, documents: nil, logo_url: nil, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Some parameter documentations has been truncated, see Models::DirUpdateInfringementParams for more details.

Push a fix for a DIR that is suspended with an open infringement claim back into vetting. POST /dir/{dir_id}/submit is blocked while a claim is open, so this is the customer-callable path to update the DIR's content and re-certify before Telnyx adjudicates the claim. All four certification booleans must be true. Optional content fields (display_name, logo_url, call_reasons, documents) update the DIR; documents are append-only.

Parameters:

Returns:

See Also:



349
350
351
352
353
354
355
356
357
358
 
# File 'lib/telnyx/resources/dir.rb', line 349

def update_infringement(dir_id, params)
  parsed, options = Telnyx::DirUpdateInfringementParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["dir/%1$s/infringement_update", dir_id],
    body: parsed,
    model: Telnyx::DirWrapped,
    options: options
  )
end