API Details

• API supports optional filtering using query params. All query params except phoneNumber and businessProfileId allow you to include the same query parameter multiple times with different values. The API will return results that match any of the provided values.
• detailedStatus (carrier/feature level) is a granular status that tells you where each carrier is in the approval process of your phone number for spam and branding.
  • pending.initialOptIn - first-time registration (new number or coming from opt-out).
  • pending.optIn - re-registration (number has been through the process before). Both are "pending" states, but initialOptIn indicates it's the first submission, while optIn indicates a subsequent change.
  • submitted.optIn - opt-in submitted to carrier.
  • approved.optIn - opt-in approved by carrier.
  • rejected.optIn - opt-in rejected by carrier.
  • submitted.optOut - opt-out submitted to carrier.
  • pending.optOut - opt-out pending.
  • approved.optOut - opt-out approved by carrier.
  • rejected.optOut - opt-out rejected by carrier.
• status (phone number level) is an overall summary status of where your phone number is in the review process:
  • submitted for review (highest priority) - if there are any pending.* or submitted.* detailedStatuses.
  • rejected - for rejected.* detailedStatuses.
  • approved - for approved.* detailedStatuses.
  • unregistered (lowest priority) - fallback, or approved.optOut detailedStatus.

Phone Number Status Flow

• When you submit a phone number for spam remediation and/or branding, its status follows this progression:
  • submitted for review: the number enters this status immediately upon submission and remains here while carrier/feature approvals are pending.
  • approved: all requested carriers and features have been approved.
  • rejected: one or more carriers or features have been rejected (if even a single carrier/feature is rejected, the overall status becomes rejected).
• The number only transitions from submitted for review once all carriers and features have received a final decision (approved or rejected).
• Deregistration: when removing spam and/or branding designations, the same flow applies. The number shows as submitted for review until all opt-outs are processed. If opting out from only some carriers/features, status will appear as approved or rejected (as in, the opt-outs have been approved or rejected). If a number is opted out of every carrier/feature combination, the status will appear as unregistered.

Example Requests

• Get all branded phone numbers: GET /v1/brandedPhoneNumbers
• Get information for a specific phone number: GET /v1/brandedPhoneNumbers?phoneNumber=%2B15551234567
• Get all phone numbers that are still in review: GET /v1/brandedPhoneNumbers?status=submitted+for+review
• Get phone numbers with status of approved or rejected: GET /v1/brandedPhoneNumbers?status=approved&status=rejected
• Get phone numbers with approved branded caller ID on AT&T: GET /v1/brandedPhoneNumbers?carrier=AT%26T&feature=brandedCallerId&status=approved.optIn
• Get phone numbers with spam remediation enabled on any carrier: GET /v1/brandedPhoneNumbers?feature=spamRemediation&status=approved.optIn

Rate Limit

If you exceed this limit, you will receive a 429 Rate Limit Exceeded response.