Toll-Free Verified Sender (Order)

Overview

Use this API to create and query the status of current Verified Sender Forms (VSFs). Failure to provide VSFs results in blocking to Canada and lower throughputs to US destinations for toll-free numbers. Submitting a VSF removes the block temporarily until the VSF is either approved, or rejected.

Authentication

This function is available via our new GraphQL API. You can read more about how to authenticate to this API here.

Mutation - to Create a new VSF

mutation (
  $businessName: String!,
  $businessRegisteredAddress: String!,
  $businessRegisteredCity: String!,
  $businessRegisteredState: String!,
  $businessRegisteredZip: String!,
  $businessContactFirstName: String!,
  $businessContactLastName: String!,
  $businessContactEmail: String!,
  $businessContactPhone: String!,
  $fortune500Or1000Company: String!,
  $numbers: [VerifiedSenderFormNumberInput!]!,
  $numbersExplanation: String!,
  $useCase: String!,
  $howDoConsumersOptIn: String!,
  $commercialMessages: String!,
  $numberPublishedLocation: String!,
  $messageSenderWebsite: String!,
  $termsAndPrivacy: String!,
  $callToAction: String!,
  $sampleMessages: [String!]!,
  $helpMessageContainsOptOutInstructions: String!,
  $stopKeywordIsSupportedAsAnOptOutMethod: String!,
  $estimatedMonthlyMessageVolume: String!,
  $previouslyAnotherMessagingServiceTraffic: String!,
  $previouslyAnotherMessagingServiceContent: String,
  $previouslyAnotherMessagingServiceNumbers: [String],
  $canadianTrafficMostly: String!,
  $covid19Related: String!,
  $attachments: [String!]!
) {
  submitVerifiedSenderForm(
    businessName: $businessName,
    businessRegisteredAddress: $businessRegisteredAddress,
    businessRegisteredCity: $businessRegisteredCity,
    businessRegisteredState: $businessRegisteredState,
    businessRegisteredZip: $businessRegisteredZip,
    businessContactFirstName: $businessContactFirstName,
    businessContactLastName: $businessContactLastName,
    businessContactEmail: $businessContactEmail,
    businessContactPhone: $businessContactPhone,
    fortune500Or1000Company: $fortune500Or1000Company,
    numbers: $numbers,
    numbersExplanation: $numbersExplanation,
    useCase: $useCase,
    howDoConsumersOptIn: $howDoConsumersOptIn,
    commercialMessages: $commercialMessages,
    numberPublishedLocation: $numberPublishedLocation,
    messageSenderWebsite: $messageSenderWebsite,
    termsAndPrivacy: $termsAndPrivacy,
    callToAction: $callToAction,
    sampleMessages: $sampleMessages,
    helpMessageContainsOptOutInstructions: $helpMessageContainsOptOutInstructions,
    stopKeywordIsSupportedAsAnOptOutMethod: $stopKeywordIsSupportedAsAnOptOutMethod,
    estimatedMonthlyMessageVolume: $estimatedMonthlyMessageVolume,
    previouslyAnotherMessagingServiceTraffic: $previouslyAnotherMessagingServiceTraffic,
    previouslyAnotherMessagingServiceContent: $previouslyAnotherMessagingServiceContent,
    previouslyAnotherMessagingServiceNumbers: $previouslyAnotherMessagingServiceNumbers,
    canadianTrafficMostly: $canadianTrafficMostly,
    covid19Related: $covid19Related,
    attachments: $attachments
  ) {
    id
    finishedAt
    insertedAt
    name
    status
    data {
      ...VerifiedSenderFormFields
    }
    
    #
  }
}

fragment VerifiedSenderFormFields on VerifiedSenderFormOrderData {
  type
  businessName
  businessRegisteredAddress
  businessRegisteredCity
  businessRegisteredState
  businessRegisteredZip
  businessContactFirstName
  businessContactLastName
  businessContactEmail
  businessContactPhone
  fortune500Or1000Company
  numbers {
    number
  }
  numbersExplanation
  useCase
  howDoConsumersOptIn
  commercialMessages
  numberPublishedLocation
  messageSenderWebsite
  termsAndPrivacy
  callToAction
  sampleMessages
  helpMessageContainsOptOutInstructions
  stopKeywordIsSupportedAsAnOptOutMethod
  estimatedMonthlyMessageVolume
  previouslyAnotherMessagingServiceTraffic
  previouslyAnotherMessagingServiceContent
  previouslyAnotherMessagingServiceNumbers
  canadianTrafficMostly
  covid19Related
}

Sample Arugments

### Arguments
{
  "businessName": "[TESTTEST] ACME Inc.",
  "businessRegisteredAddress": "[TESTTEST] Street 1B",
  "businessRegisteredCity": "[TESTTEST] Denver",
  "businessRegisteredState": "Colorado",
  "businessRegisteredZip": "123467",
  "businessContactFirstName": "John",
  "businessContactLastName": "Doe",
  "businessContactEmail": "[e-mail]",
  "businessContactPhone": "12345678910",
  "fortune500Or1000Company": "no",
  "numbers": [
    {
      "number": "12345678910"
    },
    {
      "number": "12345678911"
    }
  ],
  "numbersExplanation": "",
  "useCase": "[TESTTEST] actions, discounts, etc.",
  "howDoConsumersOptIn": "via website",
  "commercialMessages": "yes",
  "numberPublishedLocation": "https://acme.org/numbers",
  "messageSenderWebsite": "https://acme.org",
  "termsAndPrivacy": "https://acme.org/terms",
  "callToAction": "whoa",
  "sampleMessages": [
    "this is a sample message"
  ],
  "helpMessageContainsOptOutInstructions": "yes",
  "stopKeywordIsSupportedAsAnOptOutMethod": "yes",
  "estimatedMonthlyMessageVolume": "10000",
  "previouslyAnotherMessagingServiceTraffic": "yes, on Bandwidth",
  "previouslyAnotherMessagingServiceContent": "hello customer",
  "previouslyAnotherMessagingServiceNumbers": [
    "123456789"
  ],
  "canadianTrafficMostly": "unsure",
  "covid19Related": "unsure",
  "attachments": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="]
}

Query - to List VSF Orders

Use the below query to list your Verified Sender Form Orders and retrieve the status of the request.

query($page: Int, $publicId: String, $type: String, $addedStartDate: DateTime, $addedEndDate: DateTime) {
  orders(page: $page, publicId: $publicId, type: $type, addedStartDate: $addedStartDate, addedEndDate: $addedEndDate) {
    page
    pageSize
    totalPages
    orders {
      id
      publicId
      name
      insertedAt
      data {
        ...VerifiedSenderFormFields
      }
    }
  }
}

fragment VerifiedSenderFormFields on VerifiedSenderFormOrderData {
  type
  businessName
  businessRegisteredAddress
  businessRegisteredCity
  businessRegisteredState
  businessRegisteredZip
  businessContactFirstName
  businessContactLastName
  businessContactEmail
  businessContactPhone
  fortune500Or1000Company
  numbers {
    number
  }
  numbersExplanation
  useCase
  howDoConsumersOptIn
  commercialMessages
  numberPublishedLocation
  messageSenderWebsite
  termsAndPrivacy
  callToAction
  sampleMessages
  helpMessageContainsOptOutInstructions
  stopKeywordIsSupportedAsAnOptOutMethod
  estimatedMonthlyMessageVolume
  previouslyAnotherMessagingServiceTraffic
  previouslyAnotherMessagingServiceContent
  previouslyAnotherMessagingServiceNumbers
  canadianTrafficMostly
  covid19Related
}

Sample Arugments

### Arguments (all are optional)
{
  "page": 1,
  "publicId": "VSF",
  "type": "verified_sender_form",
  "addedStartDate": "2022-01-01T12:00:00Z",
  "addedEndDate": "2022-12-01T12:00:00Z"
}