Toll-Free Verified Sender (Order)

Submit a Toll-Free Verified Sender Form and list your VSF orders with the GraphQL API. Unverified toll-free numbers are blocked to Canada and throttled to the US.

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 GraphQL API. You can read more about how to authenticate to this API in GraphQL API & Authentication.

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 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": "Text JOIN to 12345678910 to receive offers",
  "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 Arguments

All arguments are optional.

{
  "page": 1,
  "publicId": "VSF",
  "type": "verified_sender_form",
  "addedStartDate": "2022-01-01T12:00:00Z",
  "addedEndDate": "2022-12-01T12:00:00Z"
}