# Toll-Free Numbers Verification API ## Overview A toll-free number can be used to send messages in US & Canada once it passes an additional verification process. Users who don’t verify their toll-free numbers will be blocked from sending messages as of November 8, 2023.
A verified toll-free number ensures that the business owning the number is identified, and that the message's content has been reviewed and does not oppose the Disallowed Content Policy. This process ensures better deliverability and less filtration.
To set up a new channel to send SMS messages using a toll-free number the following steps are required. ## API Access The following API requests can only be made using a valid access key, and attached to an access role, with an access policy that at least specifies the permissions to the resources outlined in each section below. Learn more about [API access](https://docs.messagebird.com/api/api-access). ## Find an available number If you do not already have a US or Canadian toll-free number available in your workspace you can find one to purchase. {% hint style="info" %} use the search parameter `types=toll-free` to only search for Toll Free Numbers {% endhint %} ## GET /organizations/{organizationId}/numbers-stock-items > List all available numbers in stock. ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage a number within a workspace.","name":"numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryLimit":{"description":"Limits the number of results to return per page. The default value is 10 and maximum is 99. If the nextPageToken is defined on response, you can use it to get remaining numbers. To know more, refer to the pagination section.\n","in":"query","name":"limit","schema":{"default":10,"maximum":99,"minimum":1,"type":"integer"}},"queryCursor":{"description":"Pagination token that keeps of track of the current position in the list. Use it to query remaining results. If not provided, the first page is returned. To learn more about the pagination, please refer to the pagination section on API Access Common API Usage section.","in":"query","name":"pageToken","schema":{"maxLength":8000,"type":"string"}},"queryCountryCodes":{"allowEmptyValue":false,"in":"query","name":"countryCodes","schema":{"description":"A 2-digit ISO 3166-1 country code array.","items":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":"array"}},"queryLongCodeNumberTypes":{"allowEmptyValue":false,"description":"The number type depending on its purpose. Local for regional use, national for countrywide use, mobile for mobile networks, or toll-free for caller-free charging.","in":"query","name":"types","schema":{"items":{"$ref":"#/components/schemas/LongCodeNumberType"},"type":"array"}},"queryNumberFeatures":{"allowEmptyValue":false,"description":"The number capabilities, which can be voice, SMS, and MMS for inbound, outbound, or two-way communication, plus WhatsApp.","in":"query","name":"features","schema":{"items":{"$ref":"#/components/schemas/NumberFilterFeature"},"minItems":1,"type":"array"}},"queryNumberPrefix":{"description":"Used to filter numbers by area code. Accepts either bare area code digits (e.g. `205` for Alabama) or a full E.164 prefix (e.g. `+1205`). Partial prefixes are supported for autocomplete use cases (e.g. `+120` matches all numbers in area codes 202, 203, 205, 206, 207, 208, 209). Must be used together with the `countryCodes` filter.","in":"query","name":"prefix","schema":{"maxLength":250,"minLength":1,"type":"string"}},"queryTesting":{"in":"query","name":"testing","schema":{"type":"boolean"}}},"schemas":{"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"LongCodeNumberType":{"type":"string","description":"The type of long code number.","enum":["local","national","toll-free","mobile"]},"NumberFilterFeature":{"type":"string","enum":["voice-outbound","voice-inbound","sms-outbound","sms-inbound","mms-outbound","mms-inbound","whatsapp"]},"NumberStockItem":{"type":"object","required":["id","countryCode","type","numberString","capabilities","monthlyPrice"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the stock item."},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"numberString":{"type":"string"},"capabilities":{"$ref":"#/components/schemas/PhoneNumberCapabilities"},"monthlyPrice":{"$ref":"#/components/schemas/Money"},"backOrderRequired":{"type":"boolean","description":"Whether back order is required for this item, available but it is not in the local inventory"},"backOrderStockId":{"type":"string","description":"The stock id of the back order item, to be used when creating back order","nullable":true}}},"PhoneNumberCapabilities":{"type":"object","description":"Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.","required":["voice","sms","mms"],"properties":{"voice":{"$ref":"#/components/schemas/PhoneNumberCapability"},"sms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"mms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"whatsapp":{"$ref":"#/components/schemas/PhoneNumberCapability"}}},"PhoneNumberCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"Money":{"type":"object","title":"Money","additionalProperties":false,"description":"Money combines an amount of money with its currency.","nullable":true,"properties":{"currencyCode":{"$ref":"#/components/schemas/Currency"},"amount":{"$ref":"#/components/schemas/Amount"},"exponent":{"$ref":"#/components/schemas/Exponent"}},"required":["currencyCode","amount","exponent"]},"Currency":{"title":"Currency Code","description":"Currency as ISO 4217 code (three digits). An example would be `EUR` for Euro.","type":"string","enum":["EUR","USD","GBP","AUD","SGD","IDR","INR","MXN"]},"Amount":{"type":"integer","format":"int64"},"Exponent":{"description":"Usually a negative number to specify the exponent for decimal precision. e.g., `1540 * (10^-2) = 15.4`","type":"integer","format":"int32","minimum":-10},"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.","type":"string"}},"type":"object"},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/organizations/{organizationId}/numbers-stock-items":{"get":{"operationId":"listOrganizationNumbersStockItems","summary":"List all available numbers in stock.","parameters":[{"$ref":"#/components/parameters/queryLimit"},{"$ref":"#/components/parameters/queryCursor"},{"$ref":"#/components/parameters/queryCountryCodes"},{"$ref":"#/components/parameters/queryLongCodeNumberTypes"},{"$ref":"#/components/parameters/queryNumberFeatures"},{"$ref":"#/components/parameters/queryNumberPrefix"},{"$ref":"#/components/parameters/queryTesting"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/NumberStockItem"},"type":"array"}},"required":["results"],"type":"object"},{"$ref":"#/components/schemas/pagination"}]}}},"description":"OK"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Invalid filter"}},"tags":["numbers"]}}}} ``` ## Purchase a number Once you have found an available number you can purchase this by providing the `numberStockItemIds` matching the `id` your previous call returned A successful request to this endpoint will start a recurring monthly subscription based on the monthly cost of the number. ## Buy Long Code Numbers > Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.
```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage long code numbers.","name":"long_code_numbers"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"CreateWorkspaceLongCodeNumbers":{"type":"object","additionalProperties":false,"required":["numberStockItemIds"],"properties":{"numberStockItemIds":{"type":"array","maxItems":25,"description":"The unique identifiers of the numbers you want to buy. You can buy up to 25 numbers at a time.\nThis operation will incur wallet charges for the numbers. Before buying the number, you must reserve it.\n","items":{"type":"string","format":"uuid"}}}},"WorkspaceLongCodeNumber":{"type":"object","allOf":[{"$ref":"#/components/schemas/LongCodeNumberFragment"},{"type":"object","required":["endpoint"],"properties":{"endpoint":{"$ref":"#/components/schemas/EndpointFragment"}}}]},"LongCodeNumberFragment":{"type":"object","required":["id","endpointId","numberString","countryCode","capabilities","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the long code number. The endpoint ID is the same."},"endpointId":{"type":"string","format":"uuid","description":"The unique identifier of the endpoint. The long conde ID is the same."},"numberString":{"type":"string","description":"The phone number in E.164 format."},"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"capabilities":{"$ref":"#/components/schemas/PhoneNumberCapabilities"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"order":{"$ref":"#/components/schemas/LongCodeNumberOrder","description":"The order that created this long code number. It contains information such as the capabilities, order status and type."},"deprovisionAt":{"type":"string","format":"date-time","description":"The date and time when the long code number should be deprovisioned."}}},"NumbersCountryCode":{"type":"string","format":"iso3166-1","description":"The country code in ISO 3166-1 alpha-2 format."},"LongCodeNumberType":{"type":"string","description":"The type of long code number.","enum":["local","national","toll-free","mobile"]},"PhoneNumberCapabilities":{"type":"object","description":"Capabilities of the phone number. It shows if the phone number supports voice, sms and/or mms.","required":["voice","sms","mms"],"properties":{"voice":{"$ref":"#/components/schemas/PhoneNumberCapability"},"sms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"mms":{"$ref":"#/components/schemas/PhoneNumberCapability"},"whatsapp":{"$ref":"#/components/schemas/PhoneNumberCapability"}}},"PhoneNumberCapability":{"type":"object","required":["inbound","outbound"],"properties":{"inbound":{"type":"boolean","description":"Whether the number supports inbound use cases."},"outbound":{"type":"boolean","description":"Whether the number supports outbound use cases."}}},"LongCodeNumberOrder":{"type":"object","required":["countryCode","type","capabilities","status","createdAt","updatedAt"],"properties":{"countryCode":{"$ref":"#/components/schemas/NumbersCountryCode"},"type":{"$ref":"#/components/schemas/LongCodeNumberType"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}},"prefix":{"type":"string"},"status":{"$ref":"#/components/schemas/LongCodeNumberOrderStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointCapabilityName":{"type":"string","enum":["voice","sms","mms","whatsapp","email","rcs-google"]},"LongCodeNumberOrderStatus":{"type":"string","enum":["draft","submitted","processing","fulfilled","rejected","cancelled"]},"EndpointFragment":{"type":"object","description":"A representation of an endpoint. It contains details such as the capabilities, dependencies, and more.","required":["id","type","instanceId","name","capabilities","provisioningStatus","createdAt","updatedAt"],"properties":{"id":{"$ref":"#/components/schemas/EndpointId"},"type":{"$ref":"#/components/schemas/EndpointType"},"instanceId":{"$ref":"#/components/schemas/InstanceId"},"name":{"$ref":"#/components/schemas/EndpointName"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapability"}},"dependencies":{"type":"array","description":"The dependencies of the endpoint. It shows the connectors that the endpoint is connected to.","items":{"$ref":"#/components/schemas/EndpointDependency"}},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}},"provisioningStatus":{"$ref":"#/components/schemas/EndpointProvisioningStatus"},"whatsApp":{"description":"WhatsApp pre-verification details for this endpoint, if applicable. Only present for long code numbers from WhatsApp-capable providers.","nullable":true,"$ref":"#/components/schemas/WorkspaceWhatsAppNumber"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EndpointId":{"type":"string","format":"uuid","description":"The ID of the endpoint."},"EndpointType":{"type":"string","description":"The type of the endpoint. It can be a long code number, short code number, alpha number, ip pool, or rcs google agent.","enum":["long-code-number","short-code-number","alpha-number","ip-pool","rcs-google-agent"]},"InstanceId":{"type":"string","format":"uuid","description":"The unique identifier of the instance."},"EndpointName":{"type":"string","description":"The name of the endpoint. For some cases it will be the number in international format as string."},"EndpointCapability":{"type":"object","description":"The capability of the endpoint. It shows what capabilities the endpoint supports and which direction (inbound, which means receiving messages, and outbound, which means sending messages). Also, it shows the status for that capability/direction combination.","discriminator":{"propertyName":"name","mapping":{"sms":"#/components/schemas/EndpointCapabilitySMS","mms":"#/components/schemas/EndpointCapabilityMMS","voice":"#/components/schemas/EndpointCapabilityVoice","whatsapp":"#/components/schemas/EndpointCapabilityWhatsapp","email":"#/components/schemas/EndpointCapabilityEmail","rcs-google":"#/components/schemas/EndpointCapabilityRcsGoogle"}},"oneOf":[{"$ref":"#/components/schemas/EndpointCapabilitySMS"},{"$ref":"#/components/schemas/EndpointCapabilityMMS"},{"$ref":"#/components/schemas/EndpointCapabilityVoice"},{"$ref":"#/components/schemas/EndpointCapabilityWhatsapp"},{"$ref":"#/components/schemas/EndpointCapabilityEmail"},{"$ref":"#/components/schemas/EndpointCapabilityRcsGoogle"}]},"EndpointCapabilitySMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["sms"]}}}]},"EndpointCapabilityFields":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/EndpointCapabilityName"},"inbound":{"$ref":"#/components/schemas/InboundEndpointCapability"},"outbound":{"$ref":"#/components/schemas/OutboundEndpointCapability"}}},"InboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityStatus":{"type":"string","enum":["active","inactive","available","unavailable"]},"EndpointIssue":{"type":"string","description":"The issue of the endpoint. It indicates what's wrong with the endpoint and the reason why traffic is deactivated in that case.","enum":["subscription-is-not-active","setup-fee-is-not-paid","capability-is-not-supported","compliance-requirement-not-satisfied","brand-not-ready","destination-brand-not-ready","use-case-not-ready","kyc-form-grace-period-has-ended","whatsapp-not-pre-verified"]},"OutboundEndpointCapability":{"type":"object","nullable":true,"required":["status"],"properties":{"status":{"$ref":"#/components/schemas/EndpointCapabilityStatus"},"destinationStatuses":{"type":"object","properties":{"active":{"type":"number"},"inactive":{"type":"number"},"available":{"type":"number"},"unavailable":{"type":"number"}}},"supportsDestinations":{"type":"boolean","description":"Whether the number supports destinations"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/EndpointIssue"}}}},"EndpointCapabilityMMS":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["mms"]}}}]},"EndpointCapabilityVoice":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["voice"]},"useCaseType":{"$ref":"#/components/schemas/EndpointVoiceUseCaseType"}}}]},"EndpointVoiceUseCaseType":{"type":"string","enum":["contact-centre"]},"EndpointCapabilityWhatsapp":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["whatsapp"]}}}]},"EndpointCapabilityEmail":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["email"]}}}]},"EndpointCapabilityRcsGoogle":{"allOf":[{"$ref":"#/components/schemas/EndpointCapabilityFields"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","enum":["rcs-google"]}}}]},"EndpointDependency":{"type":"object","discriminator":{"propertyName":"type","mapping":{"connector":"#/components/schemas/EndpointDependencyConnector"}},"oneOf":[{"$ref":"#/components/schemas/EndpointDependencyConnector"}]},"EndpointDependencyConnector":{"type":"object","required":["connectorId","connectorTemplateRef"],"properties":{"type":{"type":"string","enum":["connector"]},"connectorId":{"type":"string","format":"uuid"},"connectorTemplateRef":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/EndpointCapabilityName"}}}},"EndpointProvisioningStatus":{"type":"string","enum":["provisioned","provisioning","deprovisioned","deprovisioning"]},"WorkspaceWhatsAppNumber":{"type":"object","description":"WhatsApp number pre-verification details.","properties":{"whatsAppId":{"type":"string"},"status":{"$ref":"#/components/schemas/WhatsAppNumberStatus"},"stage":{"type":"string"},"attempt":{"type":"integer"},"nextAttemptAt":{"type":"string","format":"date-time"},"verificationExpiresAt":{"type":"string","format":"date-time","nullable":true},"requestedCodeAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"WhatsAppNumberStatus":{"type":"string","description":"WhatsApp number status","enum":["unknown","already-exists","installed","verified","not-verified","expired"]},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/numbers-long-code":{"post":{"operationId":"createWorkspaceLongCodeNumbers","description":"Assigns Long Code Numbers to the current workspace, charging the wallet for their subscription price. When creating LCNs as a User, all specified Number Stock Items should be reserved.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceLongCodeNumbers"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"allOf":[{"properties":{"results":{"items":{"$ref":"#/components/schemas/WorkspaceLongCodeNumber"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"Created"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Wallet reached limit"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Long Code Number not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Buy Long Code Numbers","tags":["long_code_numbers"]}}}} ``` ## Submit a verification application for a toll-free number(s) Before you can use a toll-free number to send SMS messages, you must submit a toll-free number verification request and wait for it to be approved. {% hint style="danger" %} To reduce the likelihood of rejection, ensure you are familiar with TFN registration examples and best practices. Specifically * Check [this article ](https://docs.bird.com/applications/channels/channels/supported-channels/sms/concepts/sms-registration/use-case-requirements-for-sms-registration)for tips on how to write an effective `useCaseSummary` * Check [this article](https://docs.bird.com/applications/channels/channels/supported-channels/sms/concepts/sms-registration/setting-up-a-consent-gathering-flow) on how to write an effective `optInWorkflowDescription` Most TFN rejections are caused by unclear or incomplete `useCaseSummary and/or optInWorkflowDescription` {% endhint %} {% hint style="info" %} You can submit one toll-free number per verification request. You are not allowed to submit the same number twice, unless the previous submission was resolved with status Rejected or Verified. {% endhint %} ## POST /workspaces/{workspaceId}/tfn-verifications > Create TfnVerification ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage tfn verifications.","name":"tfn_verifications"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryValidate":{"description":"When set, only validates the request payload without mutating any data.","in":"query","name":"validate","schema":{"type":"boolean"}}},"schemas":{"CreateTfnVerificationRequest":{"allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"},{"type":"object","required":["phoneNumbers"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string","format":"uuid"}},"testMode":{"type":"boolean"},"brandKycFormEntryId":{"type":"string","format":"uuid"}}}]},"TfnVerificationFields":{"type":"object","required":["businessName","businessAddr1","businessZip","businessCity","businessState","businessCountry","businessContactFirstName","businessContactLastName","businessContactEmail","businessContactPhone","corporateWebsite","messageVolume","useCase","useCaseSummary","productionMessageContent","optInWorkflowDescription","optInWorkflowImageUrLs"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"}},"businessName":{"type":"string","maxLength":500},"businessRegistrationNumber":{"type":"string","maxLength":100,"description":"Optional business registration number (TaxID). Used for toll-free verification."},"businessRegistrationIssuingCountry":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"],"description":"Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted."},"businessRegistrationType":{"type":"string","enum":["EIN","CBN","NEQ","PROVINCIAL_NUMBER","CRN","VAT","ACN","ABN","BRN","SIREN","SIRET","NZBN","UST_IDNR","CIF","NIF","CNPJ","UID","OTHER"],"description":"Type of business registration:\n- EIN: Employer Identification Number (US)\n- CBN: Canada Business Number (CA)\n- NEQ: Quebec Enterprise Number (CA)\n- PROVINCIAL_NUMBER: Provincial Business Number (CA)\n- CRN: Company Registration Number (GB, HK)\n- VAT: Value-added Tax Identification Number (GB, IE, BR, NL)\n- ACN: Australian Company Number (AU)\n- ABN: Australian Business Number (AU)\n- BRN: Business Registration Number (HK)\n- SIREN: INSEE identification number (FR)\n- SIRET: Establishment identification number (FR)\n- NZBN: New Zealand Business Number (NZ)\n- UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)\n- CIF: Código de Identificación Fiscal (ES)\n- NIF: Número de Identificación Fiscal (ES)\n- CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)\n- UID: Unternehmens-Identifikationsnummer (CH)\n- OTHER: Other registration types (covers additional countries including SE)\n"},"entityType":{"type":"string","enum":["SOLE_PROPRIETOR","PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"],"description":"Type of business entity. Required if businessRegistrationNumber is provided."},"businessAddr1":{"type":"string","maxLength":500},"businessAddr2":{"type":"string","maxLength":500},"businessZip":{"type":"string","maxLength":500},"businessCity":{"type":"string","maxLength":500},"businessState":{"type":"string","maxLength":500},"businessCountry":{"type":"string","maxLength":500},"businessContactFirstName":{"type":"string","maxLength":500},"businessContactLastName":{"type":"string","maxLength":500},"businessContactEmail":{"type":"string","maxLength":500},"businessContactPhone":{"type":"string","maxLength":500},"corporateWebsite":{"type":"string","maxLength":500},"messageVolume":{"type":"string","enum":["10","100","1000","10000","100000","250000","500000","750000","1000000","5000000","10000000+"]},"useCase":{"type":"string","maxLength":500},"useCaseSummary":{"type":"string","maxLength":500},"productionMessageContent":{"type":"string","maxLength":1000},"optInWorkflowDescription":{"type":"string","maxLength":500},"optInWorkflowImageUrLs":{"type":"array","items":{"type":"string","maxLength":1000}},"additionalInformation":{"type":"string","maxLength":500},"isvReseller":{"type":"string","maxLength":500}}},"TfnVerificationValidationResponse":{"type":"object","properties":{"brandKycFromId":{"type":"string","format":"uuid"},"fields":{"$ref":"#/components/schemas/TfnVerificationFields"},"error":{"$ref":"#/components/schemas/ValidationError"}}},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}},"TfnVerification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"verificationRequestId":{"type":"string"},"longCodeNumberIds":{"type":"array","items":{"type":"string","format":"uuid"}},"verificationRequestData":{"type":"object","allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"}]},"status":{"type":"string","enum":["submitted","in-progress","verified","rejected"]},"statusMessage":{"$ref":"#/components/schemas/StatusMessage"},"testMode":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"StatusMessage":{"type":"object","properties":{"statusCode":{"type":"string"},"declineReasonDescription":{"type":"string"},"resubmitAllowed":{"type":"boolean"}}},"RequestError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}},"paths":{"/workspaces/{workspaceId}/tfn-verifications":{"post":{"operationId":"createTfnVerification","parameters":[{"$ref":"#/components/parameters/queryValidate"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTfnVerificationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TfnVerificationValidationResponse"}}},"description":"Validation Response"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TfnVerification"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}},"description":"Bad request"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Create TfnVerification","tags":["tfn_verifications"]}}}} ``` {% tabs %} {% tab title="Request" %} ``` { "businessName": "string", "businessAddr1": "string", "businessAddr2": "string", "businessZip": "string", "businessCity": "string", "businessState": "string", "businessCountry": "string", "businessContactFirstName": "string", "businessContactLastName": "string", "businessContactEmail": "string", "businessContactPhone": "string", "corporateWebsite": "string", "messageVolume": "10", "useCase": "string", "useCaseSummary": "string", "productionMessageContent": "string", "optInWorkflowDescription": "string", "optInWorkflowImageUrLs": [ "string" ], "additionalInformation": "string", "isvReseller": "string", "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "phoneNumbers": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "testMode": true } ``` {% endtab %} {% endtabs %} To make this call, you must provide following parameters: | Parameter | Description | | -------------------------------------- | -------------------------------------------------------------------------------------- | | businessName | The name of the Business using Toll Free Number. | | businessAddr1 | The address of the Business using Toll Free Number. | | businessAddr2 (optional field) | The address of the Business using Toll Free Number. | | businessCity | The city of the Business using Toll Free Number. | | businessState | The state of the Business using Toll Free Number. | | businessZip | The zip/postal code of the Business using Toll Free Number. | | businessCountry | Country of the Business using Toll Free Number. | | corporateWebsite | The website of the Business using Toll Free Number. | | businessContactFirstName | Business contact first name. | | businessContactLastName | Business contact last name. | | businessContactEmail | Business contact email address. | | businessContactPhone | Business contact phone number. | | messageVolume | Estimate monthly volume of messages from the Toll Free Number. See more details below. | | phoneNumbers | IDs of Toll-Free numbers. | | useCase | The Category of the use case. See below types of UseCases | | useCaseSummary | Please provide a general idea of the use case and customer. | | productionMessageContent | Example of message content. | | optInWorkflowDescription | Description of the opt in workflow. | | optInWorkflowImageUrLs | Images showing the opt in workflow. | | additionalInformation (optional field) | Any additional information. | | isvReseller (optional field) | ISV Name. | #### UseCase categories must only be of these types ``` [ "2FA", "App Notifications", "Appointments", "Auctions", "Auto Repair Services", "Bank Transfers", "Billing", "Booking Confirmations", "Business Updates", "Career Training", "Chatbot", "Contests", "Courier Services & Deliveries", "Emergency Alerts", "Events & Planning", "Financial Services", "Fraud Alerts", "Fundraising", "General Marketing", "General School Updates", "HR / Staffing", "Healthcare Services", "Housing Community Updates", "Insurance Services", "Job Dispatch", "Mixed", "Motivational Reminders", "Notary Notifications", "Order Notifications", "Public Works", "Real Estate Services", "Religious Services", "Repair and Diagnostics Alerts", "Rewards Program", "Surveys", "System Alerts", "Voting Reminders", "Webinar Reminders", "Workshop Alerts", "Zipwhip Testing" ] ``` Message Volume can only be of this type: ``` 10; 100; 1,000; 10,000; 100,000; 250,000; 500,000; 750,000; 1,000,000; 5,000,000; 10,000,000+ ``` Fields below are not required for the submission: ``` businessAddr2, additionalInformation, isvReseller ``` #### Responses **201: Created** ``` { "businessName": "string", "businessAddr1": "string", "businessAddr2": "string", "businessZip": "string", "businessCity": "string", "businessState": "string", "businessCountry": "string", "businessContactFirstName": "string", "businessContactLastName": "string", "businessContactEmail": "string", "businessContactPhone": "string", "corporateWebsite": "string", "messageVolume": "10", "useCase": "string", "useCaseSummary": "string", "productionMessageContent": "string", "optInWorkflowDescription": "string", "optInWorkflowImageUrLs": [ "string" ], "additionalInformation": "string", "isvReseller": "string", "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "phoneNumbers": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "testMode": true } ``` **422: Unprocessable Entity (Invalid verification submission)** ``` { "code": "string", "message": "string", "details": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] } } ``` **400: Bad request** ``` { "code": "string", "message": "string" } ``` ## Fetch the status of a toll-free number verification Once you submit your verification request, you must wait for it to be reviewed. You will be informed about the status of your submission in the portal, but you can also use the API to fetch your verification request status. #### Statuses | Statuses | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Submitted | Verification is submitted and waiting to be reviewed | | InProgress | Verification is being reviewed by authority. Additional information may be requested. In case of API integration please inspect the \`statusMessage\` object for more information. | | Verified |

Verification submission has been approved, and the number is ready to be used.


| | Rejected | Verification submission has been rejected. | ## GET /workspaces/{workspaceId}/tfn-verifications/{verificationId} > Get Workspace TfnVerification ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage tfn verifications.","name":"tfn_verifications"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"TfnVerification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"verificationRequestId":{"type":"string"},"longCodeNumberIds":{"type":"array","items":{"type":"string","format":"uuid"}},"verificationRequestData":{"type":"object","allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"}]},"status":{"type":"string","enum":["submitted","in-progress","verified","rejected"]},"statusMessage":{"$ref":"#/components/schemas/StatusMessage"},"testMode":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"TfnVerificationFields":{"type":"object","required":["businessName","businessAddr1","businessZip","businessCity","businessState","businessCountry","businessContactFirstName","businessContactLastName","businessContactEmail","businessContactPhone","corporateWebsite","messageVolume","useCase","useCaseSummary","productionMessageContent","optInWorkflowDescription","optInWorkflowImageUrLs"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"}},"businessName":{"type":"string","maxLength":500},"businessRegistrationNumber":{"type":"string","maxLength":100,"description":"Optional business registration number (TaxID). Used for toll-free verification."},"businessRegistrationIssuingCountry":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"],"description":"Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted."},"businessRegistrationType":{"type":"string","enum":["EIN","CBN","NEQ","PROVINCIAL_NUMBER","CRN","VAT","ACN","ABN","BRN","SIREN","SIRET","NZBN","UST_IDNR","CIF","NIF","CNPJ","UID","OTHER"],"description":"Type of business registration:\n- EIN: Employer Identification Number (US)\n- CBN: Canada Business Number (CA)\n- NEQ: Quebec Enterprise Number (CA)\n- PROVINCIAL_NUMBER: Provincial Business Number (CA)\n- CRN: Company Registration Number (GB, HK)\n- VAT: Value-added Tax Identification Number (GB, IE, BR, NL)\n- ACN: Australian Company Number (AU)\n- ABN: Australian Business Number (AU)\n- BRN: Business Registration Number (HK)\n- SIREN: INSEE identification number (FR)\n- SIRET: Establishment identification number (FR)\n- NZBN: New Zealand Business Number (NZ)\n- UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)\n- CIF: Código de Identificación Fiscal (ES)\n- NIF: Número de Identificación Fiscal (ES)\n- CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)\n- UID: Unternehmens-Identifikationsnummer (CH)\n- OTHER: Other registration types (covers additional countries including SE)\n"},"entityType":{"type":"string","enum":["SOLE_PROPRIETOR","PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"],"description":"Type of business entity. Required if businessRegistrationNumber is provided."},"businessAddr1":{"type":"string","maxLength":500},"businessAddr2":{"type":"string","maxLength":500},"businessZip":{"type":"string","maxLength":500},"businessCity":{"type":"string","maxLength":500},"businessState":{"type":"string","maxLength":500},"businessCountry":{"type":"string","maxLength":500},"businessContactFirstName":{"type":"string","maxLength":500},"businessContactLastName":{"type":"string","maxLength":500},"businessContactEmail":{"type":"string","maxLength":500},"businessContactPhone":{"type":"string","maxLength":500},"corporateWebsite":{"type":"string","maxLength":500},"messageVolume":{"type":"string","enum":["10","100","1000","10000","100000","250000","500000","750000","1000000","5000000","10000000+"]},"useCase":{"type":"string","maxLength":500},"useCaseSummary":{"type":"string","maxLength":500},"productionMessageContent":{"type":"string","maxLength":1000},"optInWorkflowDescription":{"type":"string","maxLength":500},"optInWorkflowImageUrLs":{"type":"array","items":{"type":"string","maxLength":1000}},"additionalInformation":{"type":"string","maxLength":500},"isvReseller":{"type":"string","maxLength":500}}},"StatusMessage":{"type":"object","properties":{"statusCode":{"type":"string"},"declineReasonDescription":{"type":"string"},"resubmitAllowed":{"type":"boolean"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tfn-verifications/{verificationId}":{"get":{"operationId":"getWorkspaceTfnVerification","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TfnVerification"}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"TfnVerification not found"}},"summary":"Get Workspace TfnVerification","tags":["tfn_verifications"]}}}} ``` #### Responses **200 OK:** ``` { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "verificationRequestId": "string", "phoneNumbers": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "verificationRequestData": { "businessName": "string", "businessAddr1": "string", "businessAddr2": "string", "businessZip": "string", "businessCity": "string", "businessState": "string", "businessCountry": "string", "businessContactFirstName": "string", "businessContactLastName": "string", "businessContactEmail": "string", "businessContactPhone": "string", "corporateWebsite": "string", "messageVolume": "10", "useCase": "string", "useCaseSummary": "string", "productionMessageContent": "string", "optInWorkflowDescription": "string", "optInWorkflowImageUrLs": [ "string" ], "additionalInformation": "string", "isvReseller": "string" }, "status": "submitted", "statusMessage": { "StatusCode": "string", "DeclineReasonDescription": "string", "ResubmitAllowed": "string", "Message": "string" }, "testMode": true, "createdAt": "2023-10-12T13:13:15.161Z", "updatedAt": "2023-10-12T13:13:15.161Z" } ``` **404 Not Found:** ``` { "code": "string", "message": "string" } ``` ### Verification status Message If verification is rejected, some information will be provided in the DeclineReasonDescription if is in Progress, and any additional details have been required by the reviewing authority, you can find details in the `Message` field ``` "statusMessage": { "StatusCode": "string", "DeclineReasonDescription": "string", "ResubmitAllowed": "string", "Message": "string" } ``` ## Update toll-free number verification submission You can update verification submission with new information in two cases: 1. Authority has requested to add additional information. Your input is required. {% hint style="info" %} [Deadline for resubmission is 7 days from the moment of receiving notification from the verification authority.](#user-content-fn-1)[^1] Always check the ResubmissionAllow filed in the StatusMessage before using this method {% endhint %} 2. Provide more accurate verification information without request of an authority. ## PUT /workspaces/{workspaceId}/tfn-verifications/{verificationId} > Update Workspace TfnVerification submission, and submit updates to 3rd party TfnVerification API ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage tfn verifications.","name":"tfn_verifications"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"UpdateTfnVerificationRequest":{"allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"}]},"TfnVerificationFields":{"type":"object","required":["businessName","businessAddr1","businessZip","businessCity","businessState","businessCountry","businessContactFirstName","businessContactLastName","businessContactEmail","businessContactPhone","corporateWebsite","messageVolume","useCase","useCaseSummary","productionMessageContent","optInWorkflowDescription","optInWorkflowImageUrLs"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"}},"businessName":{"type":"string","maxLength":500},"businessRegistrationNumber":{"type":"string","maxLength":100,"description":"Optional business registration number (TaxID). Used for toll-free verification."},"businessRegistrationIssuingCountry":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"],"description":"Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted."},"businessRegistrationType":{"type":"string","enum":["EIN","CBN","NEQ","PROVINCIAL_NUMBER","CRN","VAT","ACN","ABN","BRN","SIREN","SIRET","NZBN","UST_IDNR","CIF","NIF","CNPJ","UID","OTHER"],"description":"Type of business registration:\n- EIN: Employer Identification Number (US)\n- CBN: Canada Business Number (CA)\n- NEQ: Quebec Enterprise Number (CA)\n- PROVINCIAL_NUMBER: Provincial Business Number (CA)\n- CRN: Company Registration Number (GB, HK)\n- VAT: Value-added Tax Identification Number (GB, IE, BR, NL)\n- ACN: Australian Company Number (AU)\n- ABN: Australian Business Number (AU)\n- BRN: Business Registration Number (HK)\n- SIREN: INSEE identification number (FR)\n- SIRET: Establishment identification number (FR)\n- NZBN: New Zealand Business Number (NZ)\n- UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)\n- CIF: Código de Identificación Fiscal (ES)\n- NIF: Número de Identificación Fiscal (ES)\n- CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)\n- UID: Unternehmens-Identifikationsnummer (CH)\n- OTHER: Other registration types (covers additional countries including SE)\n"},"entityType":{"type":"string","enum":["SOLE_PROPRIETOR","PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"],"description":"Type of business entity. Required if businessRegistrationNumber is provided."},"businessAddr1":{"type":"string","maxLength":500},"businessAddr2":{"type":"string","maxLength":500},"businessZip":{"type":"string","maxLength":500},"businessCity":{"type":"string","maxLength":500},"businessState":{"type":"string","maxLength":500},"businessCountry":{"type":"string","maxLength":500},"businessContactFirstName":{"type":"string","maxLength":500},"businessContactLastName":{"type":"string","maxLength":500},"businessContactEmail":{"type":"string","maxLength":500},"businessContactPhone":{"type":"string","maxLength":500},"corporateWebsite":{"type":"string","maxLength":500},"messageVolume":{"type":"string","enum":["10","100","1000","10000","100000","250000","500000","750000","1000000","5000000","10000000+"]},"useCase":{"type":"string","maxLength":500},"useCaseSummary":{"type":"string","maxLength":500},"productionMessageContent":{"type":"string","maxLength":1000},"optInWorkflowDescription":{"type":"string","maxLength":500},"optInWorkflowImageUrLs":{"type":"array","items":{"type":"string","maxLength":1000}},"additionalInformation":{"type":"string","maxLength":500},"isvReseller":{"type":"string","maxLength":500}}},"TfnVerification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"verificationRequestId":{"type":"string"},"longCodeNumberIds":{"type":"array","items":{"type":"string","format":"uuid"}},"verificationRequestData":{"type":"object","allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"}]},"status":{"type":"string","enum":["submitted","in-progress","verified","rejected"]},"statusMessage":{"$ref":"#/components/schemas/StatusMessage"},"testMode":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"StatusMessage":{"type":"object","properties":{"statusCode":{"type":"string"},"declineReasonDescription":{"type":"string"},"resubmitAllowed":{"type":"boolean"}}},"RequestError":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}},"ValidationError":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tfn-verifications/{verificationId}":{"put":{"operationId":"updateWorkspaceTfnVerification","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTfnVerificationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TfnVerification"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}},"description":"Bad request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"TfnVerification not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"}},"summary":"Update Workspace TfnVerification submission, and submit updates to 3rd party TfnVerification API","tags":["tfn_verifications"]}}}} ``` {% tabs %} {% tab title="Request" %} ``` { "businessName": "string", "businessAddr1": "string", "businessAddr2": "string", "businessZip": "string", "businessCity": "string", "businessState": "string", "businessCountry": "string", "businessContactFirstName": "string", "businessContactLastName": "string", "businessContactEmail": "string", "businessContactPhone": "string", "corporateWebsite": "string", "messageVolume": "10", "useCase": "string", "useCaseSummary": "string", "productionMessageContent": "string", "optInWorkflowDescription": "string", "optInWorkflowImageUrLs": [ "string" ], "additionalInformation": "string", "isvReseller": "string", "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "testMode": true } ``` {% endtab %} {% endtabs %} #### Responses **200 OK:** ```` { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "workspaceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "verificationRequestId": "string", "phoneNumbers": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "verificationRequestData": { "businessName": "string", "businessAddr1": "string", "businessAddr2": "string", "businessZip": "string", "businessCity": "string", "businessState": "string", "businessCountry": "string", "businessContactFirstName": "string", "businessContactLastName": "string", "businessContactEmail": "string", "businessContactPhone": "string", "corporateWebsite": "string", "messageVolume": "10", "useCase": "string", "useCaseSummary": "string", "productionMessageContent": "string", "optInWorkflowDescription": "string", "optInWorkflowImageUrLs": [ "string" ], "additionalInformation": "string", "isvReseller": "string" }, "status": "submitted", "statusMessage": { "StatusCode": "string", "DeclineReasonDescription": "string", "ResubmitAllowed": "string", "Message": "string" }, "testMode": true, "createdAt": "2023-10-12T13:44:03.004Z", "updatedAt": "2023-10-12T13:44:03.004Z" } ``` #### 400: Bad request Error processing the request ```json { "code": "string", "message": "string" } ```` **404 Not Found:** ``` { "code": "string", "message": "string" } ``` **422: Unprocessable Entity** ``` { "code": "string", "message": "string", "details": { "additionalProp1": [ "string" ], "additionalProp2": [ "string" ], "additionalProp3": [ "string" ] } } ``` ## Retrieve all Verification of a Workspaces ## GET /workspaces/{workspaceId}/tfn-verifications > List Workspace TfnVerifications ```json {"openapi":"3.0.3","info":{"title":"Numbers","version":"v1"},"tags":[{"description":"Manage tfn verifications.","name":"tfn_verifications"}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"parameters":{"queryTfnVerificationStatus":{"description":"Used to filter for TfnVerifications status containing the search term.","in":"query","name":"statuses","schema":{"items":{"enum":["submitted","in-progress","verified","rejected"],"minItems":1,"type":"string"},"type":"array"}}},"schemas":{"pagination":{"properties":{"nextPageToken":{"description":"The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display. To know more, refer to the pagination section.","type":"string"}},"type":"object"},"TfnVerification":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"verificationRequestId":{"type":"string"},"longCodeNumberIds":{"type":"array","items":{"type":"string","format":"uuid"}},"verificationRequestData":{"type":"object","allOf":[{"$ref":"#/components/schemas/TfnVerificationFields"}]},"status":{"type":"string","enum":["submitted","in-progress","verified","rejected"]},"statusMessage":{"$ref":"#/components/schemas/StatusMessage"},"testMode":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"TfnVerificationFields":{"type":"object","required":["businessName","businessAddr1","businessZip","businessCity","businessState","businessCountry","businessContactFirstName","businessContactLastName","businessContactEmail","businessContactPhone","corporateWebsite","messageVolume","useCase","useCaseSummary","productionMessageContent","optInWorkflowDescription","optInWorkflowImageUrLs"],"properties":{"phoneNumbers":{"type":"array","items":{"type":"string"}},"businessName":{"type":"string","maxLength":500},"businessRegistrationNumber":{"type":"string","maxLength":100,"description":"Optional business registration number (TaxID). Used for toll-free verification."},"businessRegistrationIssuingCountry":{"type":"string","enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW"],"description":"Country that issued the business registration (ISO 3166-1 alpha-2 code). Any valid country code is accepted."},"businessRegistrationType":{"type":"string","enum":["EIN","CBN","NEQ","PROVINCIAL_NUMBER","CRN","VAT","ACN","ABN","BRN","SIREN","SIRET","NZBN","UST_IDNR","CIF","NIF","CNPJ","UID","OTHER"],"description":"Type of business registration:\n- EIN: Employer Identification Number (US)\n- CBN: Canada Business Number (CA)\n- NEQ: Quebec Enterprise Number (CA)\n- PROVINCIAL_NUMBER: Provincial Business Number (CA)\n- CRN: Company Registration Number (GB, HK)\n- VAT: Value-added Tax Identification Number (GB, IE, BR, NL)\n- ACN: Australian Company Number (AU)\n- ABN: Australian Business Number (AU)\n- BRN: Business Registration Number (HK)\n- SIREN: INSEE identification number (FR)\n- SIRET: Establishment identification number (FR)\n- NZBN: New Zealand Business Number (NZ)\n- UST_IDNR: Umsatzsteuer-Identifikationsnummer (DE)\n- CIF: Código de Identificación Fiscal (ES)\n- NIF: Número de Identificación Fiscal (ES)\n- CNPJ: Cadastro Nacional Da Pessoa Jurídica (BR)\n- UID: Unternehmens-Identifikationsnummer (CH)\n- OTHER: Other registration types (covers additional countries including SE)\n"},"entityType":{"type":"string","enum":["SOLE_PROPRIETOR","PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"],"description":"Type of business entity. Required if businessRegistrationNumber is provided."},"businessAddr1":{"type":"string","maxLength":500},"businessAddr2":{"type":"string","maxLength":500},"businessZip":{"type":"string","maxLength":500},"businessCity":{"type":"string","maxLength":500},"businessState":{"type":"string","maxLength":500},"businessCountry":{"type":"string","maxLength":500},"businessContactFirstName":{"type":"string","maxLength":500},"businessContactLastName":{"type":"string","maxLength":500},"businessContactEmail":{"type":"string","maxLength":500},"businessContactPhone":{"type":"string","maxLength":500},"corporateWebsite":{"type":"string","maxLength":500},"messageVolume":{"type":"string","enum":["10","100","1000","10000","100000","250000","500000","750000","1000000","5000000","10000000+"]},"useCase":{"type":"string","maxLength":500},"useCaseSummary":{"type":"string","maxLength":500},"productionMessageContent":{"type":"string","maxLength":1000},"optInWorkflowDescription":{"type":"string","maxLength":500},"optInWorkflowImageUrLs":{"type":"array","items":{"type":"string","maxLength":1000}},"additionalInformation":{"type":"string","maxLength":500},"isvReseller":{"type":"string","maxLength":500}}},"StatusMessage":{"type":"object","properties":{"statusCode":{"type":"string"},"declineReasonDescription":{"type":"string"},"resubmitAllowed":{"type":"boolean"}}},"Error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n","minLength":5},"message":{"type":"string","minLength":5,"description":"A human-readable message that describes the error. An example is 'The request body is missing the required field `service`.'\n"},"details":{"type":"object","additionalProperties":true,"description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n"}}}}},"paths":{"/workspaces/{workspaceId}/tfn-verifications":{"get":{"operationId":"listWorkspaceTfnVerifications","parameters":[{"$ref":"#/components/parameters/queryTfnVerificationStatus"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/pagination"},{"properties":{"results":{"items":{"$ref":"#/components/schemas/TfnVerification"},"type":"array"}},"required":["results"],"type":"object"}]}}},"description":"OK"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"TfnVerification not found"}},"summary":"List Workspace TfnVerifications","tags":["tfn_verifications"]}}}} ``` {% hint style="info" %} A TFN may have multiple verifications (example the firs submission was rejected by the reviewing authority ) but only one of them can be active {% endhint %} [^1]: --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/numbers-api/api-reference/toll-free-numbers-verification-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.