@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Twilio - Lookups
@base https://lookups.twilio.com
@version 1.0.0
@auth Bearer basic
@endpoints 10
@toc PhoneNumbers(5), batch(1), RateLimits(4)

@group PhoneNumbers
@endpoint GET /v2/PhoneNumbers/{PhoneNumber}
@desc Full API documentation: https://www.twilio.com/docs/lookup/v2-api
@required {PhoneNumber: str # The phone number to lookup in E.164 or national format. Default country code is +1 (North America).}
@optional {Fields: str # A comma-separated list of fields to return. Possible values are validation, caller_name, sim_swap, call_forwarding, line_status, line_type_intelligence, identity_match, reassigned_number, sms_pumping_risk, phone_number_quality_score, pre_fill., CountryCode: str # The [country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) used if the phone number provided is in national format., FirstName: str # User’s first name. This query parameter is only used (optionally) for identity_match package requests., LastName: str # User’s last name. This query parameter is only used (optionally) for identity_match package requests., AddressLine1: str # User’s first address line. This query parameter is only used (optionally) for identity_match package requests., AddressLine2: str # User’s second address line. This query parameter is only used (optionally) for identity_match package requests., City: str # User’s city. This query parameter is only used (optionally) for identity_match package requests., State: str # User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests., PostalCode: str # User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests., AddressCountryCode: str(iso-country-code) # User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests., NationalId: str # User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests., DateOfBirth: str # User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests., LastVerifiedDate: str # The date you obtained consent to call or text the end-user of the phone number or a date on which you are reasonably certain that the end-user could still be reached at that number. This query parameter is only used (optionally) for reassigned_number package requests., VerificationSid: str # The unique identifier associated with a verification process through verify API. This query parameter is only used (optionally) for pre_fill package requests., PartnerSubId: str # The optional partnerSubId parameter to provide context for your sub-accounts, tenantIDs, sender IDs or other segmentation, enhancing the accuracy of the risk analysis.}
@returns(200) {calling_country_code: str?, country_code: str?, phone_number: str(phone-number)?, national_format: str?, valid: bool, validation_errors: [str], caller_name: map{caller_name: str, caller_type: str, error_code: int}, sim_swap: map{last_sim_swap: any, carrier_name: str, mobile_country_code: str, mobile_network_code: str, error_code: int}, call_forwarding: map{call_forwarding_enabled: bool, error_code: int(int32)}, line_type_intelligence: map{mobile_country_code: str, mobile_network_code: str, carrier_name: str, type: str, error_code: int}, line_status: map{status: str, error_code: int}, identity_match: map{first_name_match: str, last_name_match: str, address_lines_match: str, city_match: str, state_match: str, postal_code_match: str, address_country_match: str, national_id_match: str, date_of_birth_match: str, summary_score: int(int32), error_code: int(int32), error_message: str}, reassigned_number: map{last_verified_date: str, is_number_reassigned: str, error_code: str}, sms_pumping_risk: map{carrier_risk_category: str, number_blocked: bool, number_blocked_date: str(date-time), number_blocked_last_3_months: bool, sms_pumping_risk_score: int, error_code: int}, phone_number_quality_score: any, pre_fill: any, url: str(uri)} # OK

@endgroup

@group batch
@endpoint POST /v2/batch/query
@desc In Request Bulk
@optional {phone_numbers: [map{correlation_id: str, phone_number!: str, fields: [str], country_code: str, identity_match: map, reassigned_number: map, sms_pumping_risk: map}]}
@returns(200) {phone_numbers: [map]} # OK

@endgroup

@group RateLimits
@endpoint GET /v2/RateLimits
@desc Get account rate limits
@optional {Fields: [str]}
@returns(200) {rate_limits: [map]} # OK
@errors {400: Bad Request}

@endpoint GET /v2/RateLimits/Fields/{Field}/Bucket/{Bucket}
@desc Get rate limit
@required {Field: str # bucket name, Bucket: str # bucket name}
@returns(200) {field: str, limit: int(int32), bucket: str, owner: str, ttl: int(int32)} # OK
@errors {400: Bad Request, 404: Not Found}

@endpoint DELETE /v2/RateLimits/Fields/{Field}/Bucket/{Bucket}
@desc Delete rate limit
@required {Field: str # bucket name, Bucket: str # bucket name}
@returns(204) No Content
@errors {400: Bad Request}

@endpoint PUT /v2/RateLimits/Fields/{Field}/Bucket/{Bucket}
@desc Upsert rate limit
@required {Field: str # field name, Bucket: str # bucket name}
@optional {limit: int(int32) # Limit of requests for the bucket, ttl: int(int32) # Time to live of the rule}
@returns(200) {field: str, limit: int(int32), bucket: str, owner: str, ttl: int(int32)} # OK
@errors {400: Bad Request}

@endgroup

@group PhoneNumbers
@endpoint GET /v2/PhoneNumbers/{PhoneNumber}/Overrides/{Field}
@desc Get Overrides for a Phone Number for a specific field.
@required {Field: str, PhoneNumber: str}
@returns(200) {phone_number: str, original_line_type: str, overridden_line_type: str, override_reason: str, override_timestamp: str(date-time), overridden_by_account_sid: str} # OK
@errors {400: Bad Request, 404: Not Found}

@endpoint POST /v2/PhoneNumbers/{PhoneNumber}/Overrides/{Field}
@desc Create Override for a Phone Number for a specific field
@required {Field: str, PhoneNumber: str}
@optional {line_type: str(mobile/landline/tollFree/fixedVoip/nonFixedVoip/personal/premium/voicemail/sharedCost/uan/pager/unknown) # The new line type to override the original line type, reason: str # The reason for the override}
@returns(201) {phone_number: str, original_line_type: str, overridden_line_type: str, override_reason: str, override_timestamp: str(date-time), overridden_by_account_sid: str} # Created
@errors {400: Bad Request}

@endpoint PUT /v2/PhoneNumbers/{PhoneNumber}/Overrides/{Field}
@desc Update Override for a Phone Number for a specific field
@required {Field: str, PhoneNumber: str}
@optional {line_type: str(mobile/landline/tollFree/fixedVoip/nonFixedVoip/personal/premium/voicemail/sharedCost/uan/pager/unknown) # The new line type to override the original line type, reason: str # The reason for the override}
@returns(200) {phone_number: str, original_line_type: str, overridden_line_type: str, override_reason: str, override_timestamp: str(date-time), overridden_by_account_sid: str} # OK
@errors {400: Bad Request, 404: Not Found}

@endpoint DELETE /v2/PhoneNumbers/{PhoneNumber}/Overrides/{Field}
@desc Delete an Override for a Phone Number for a specific field
@required {Field: str, PhoneNumber: str}
@returns(204) No Content
@errors {400: Bad Request}

@endgroup

@end