{ "openapi": "3.0.3", "info": { "version": "0.0.1", "title": "TFN (Toll Free Numbers) Registration API", "x-metaTitle": "Vonage TFN API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage TFN API in this reference guide. Learn more in Vonage's API documentation.", "contact": { "name": "Vonage", "url": "https://developer.nexmo.com", "email": "devrel@vonage.com" }, "license": { "name": "The MIT License (MIT)", "url": "https://opensource.org/licenses/MIT" }, "description": "The Vonage TFN (Toll Free Numbers) Registration API allows you to manage Toll Free Number registrations in the US & Canada.\n\nFor more information, visit the [Vonage Developer Portal](https://developer.vonage.com).\n" }, "servers": [ { "url": "https://api.nexmo.com/tfn" } ], "tags": [ { "name": "Registrations", "description": "Endpoints allowing to create, get and update TFN registrations and get events." }, { "name": "Numbers", "description": "Endpoints allowing to manage TFN numbers." } ], "paths": { "/v1/registrations": { "post": { "operationId": "createRegistration", "summary": "Create a TFN registration", "tags": [ "Registrations" ], "security": [ { "basicAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRegistrationRequest" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/CreateRegistrationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableResourceError" }, "429": { "$ref": "#/components/responses/ThrottledError" } } } }, "/v1/registrations/{id}": { "get": { "operationId": "getRegistration", "summary": "Get the registration details by registration ID", "tags": [ "Registrations" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/pathRegistrationID" } ], "responses": { "200": { "description": "Successful response", "content": { "application/hal+json": { "schema": { "$ref": "#/components/schemas/GetRegistrationResponse" } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" } } }, "patch": { "operationId": "updateRegistration", "summary": "Update a registration", "description": "Registration can be updated if on of the following conditions is met:\n- Submission status is DRAFT or\n- Submission status is SUBMITTED and all number statuses are UPDATES_REQUIRED\n", "tags": [ "Registrations" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/pathRegistrationID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRegistrationRequest" } } } }, "responses": { "204": { "description": "Successful response" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "422": { "$ref": "#/components/responses/UnprocessableResourceError" }, "429": { "$ref": "#/components/responses/ThrottledError" } } } }, "/v1/registrations/{id}/number/{number}/events": { "get": { "operationId": "getRegistrationEvents", "summary": "Get events associated with registration and toll free number", "description": "Get events for a registration. Only the account holder can retrieve events for the tfn.\nEvents are returned in descending order with the latest events on top.\n", "tags": [ "Registrations" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/pathRegistrationID" }, { "$ref": "#/components/parameters/pathTFN" } ], "responses": { "200": { "description": "Successful response", "content": { "application/hal+json": { "schema": { "allOf": [ { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/GetEventsResponse" } } } } } }, { "$ref": "#/components/schemas/PaginatedSelfResponse" } ] } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableResourceError" } } } }, "/v1/numbers": { "get": { "operationId": "getNumber", "summary": "Get a list of number registrations", "tags": [ "Numbers" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageSize" }, { "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/NumberStatus" }, "description": "Filter by number status" }, { "in": "query", "name": "number", "schema": { "$ref": "#/components/schemas/TFN" }, "description": "Filter by specific toll-free number" }, { "in": "query", "name": "registration_id", "schema": { "$ref": "#/components/schemas/RegistrationID" }, "description": "Filter by specific registration ID" }, { "in": "query", "name": "business_name", "schema": { "$ref": "#/components/schemas/BusinessName" }, "description": "Fuzzy search by business name" } ], "responses": { "200": { "description": "List of number registrations", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "numbers": { "type": "array", "items": { "$ref": "#/components/schemas/NumberRegistrationsResponse" } } } } } }, { "$ref": "#/components/schemas/PaginatedResponse" } ] } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "422": { "$ref": "#/components/responses/UnprocessableResourceError" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "BusinessName": { "type": "string", "maxLength": 500, "description": "Parent company or organization full name.", "example": "Ericsson LM" }, "Street": { "type": "string", "maxLength": 500, "description": "Street number and name.", "example": "101 Crawfords Corner Rd" }, "City": { "type": "string", "maxLength": 500, "description": "City name", "example": "Holmdel" }, "State": { "type": "string", "maxLength": 500, "description": "State or province. For the United States, use 2-character codes, e.g., ‘CA’ for California.", "example": "CA" }, "PostalCode": { "type": "string", "maxLength": 10, "description": "Zip Code or postal code. For the United States, use a 5-digit ZIP code", "example": "21012" }, "Country": { "type": "string", "description": "Two-letter country code following the ISO 3166-2 standard", "example": "US" }, "EntityType": { "type": "string", "title": "Entity Type", "description": "Legal classification for the company/organization.\n", "enum": [ "SOLE_PROPRIETOR", "PRIVATE_PROFIT", "PUBLIC_PROFIT", "NON_PROFIT", "GOVERNMENT" ], "example": "PRIVATE_PROFIT" }, "TaxIDType": { "type": "string", "title": "Tax Identifier Type", "description": "- For the US, a Federal Tax ID or Employee Identification Number (EIN) is required.\n- For Canada, the Canada Business Number (CBN) is required.\n- Sole Proprietorship may apply without an EIN/CBN, but there will be additional checks to validate that the provided information is accurate.\n- For other country-specific registration, select the relevant option or Other.\n", "enum": [ "EIN", "CBN", "CRN", "NEQ", "PROVINCIAL_NUMBER", "VAT", "ACN", "ABN", "BRN", "SIREN", "SIRET", "NZBN", "UST-IDNR", "CIF", "NIF", "CNPJ", "UID", "OTHER" ], "example": "EIN", "default": "EIN" }, "TaxID": { "type": "string", "maxLength": 500, "title": "Tax Identifier Number", "description": "- For the US, provide the Employee Identification Number (EIN) for the company/organization.\n- For Canada, provide the Canada Business Number (CBN) for the company/organization.\n- For Sole Proprietorship, you may leave this field blank.\n- For country-specific registration types, provide the relevant Tax ID number.\n", "example": "12-3456789" }, "TaxIDIssuingCountry": { "type": "string", "maxLength": 2, "title": "Tax Identifier Issuing Country", "description": "Relevant issuing country. Two-letter ISO-2 country code.\n", "example": "US" }, "BusinessInfo": { "type": "object", "title": "Business", "description": "The content creator, not an ISV or reseller", "required": [ "name", "address", "company_website", "contact", "entity_type", "tax_id_type", "tax_id", "tax_id_issuing_country" ], "properties": { "name": { "$ref": "#/components/schemas/BusinessName" }, "address": { "type": "object", "required": [ "street", "city", "state", "postal_code", "country" ], "properties": { "street": { "$ref": "#/components/schemas/Street" }, "city": { "$ref": "#/components/schemas/City" }, "state": { "$ref": "#/components/schemas/State" }, "postal_code": { "$ref": "#/components/schemas/PostalCode" }, "country": { "$ref": "#/components/schemas/Country" } } }, "company_website": { "type": "string", "description": "Provide a publicly available website link for the company/organization. Must be a valid URL.\n", "maxLength": 500, "example": "https://www.vonage.com" }, "contact": { "type": "object", "required": [ "first_name", "last_name", "email", "phone" ], "properties": { "first_name": { "type": "string", "maxLength": 500, "description": "First name of business contact.", "example": "John" }, "last_name": { "type": "string", "description": "Last name of business contact.", "maxLength": 500, "example": "Smith" }, "email": { "type": "string", "maxLength": 500, "description": "Email address must match the company, organization or brand (DBA) name if entered.\n", "example": "john.smith@vonage.com" }, "phone": { "type": "string", "maxLength": 500, "format": "e164", "title": "Business Contact Phone Number", "description": "Phone number of business contact. Must be a valid phone number in E.164 format without the + prefix.", "example": "12125551212" } } }, "dba": { "type": "string", "maxLength": 500, "example": "Vonage Holdings Corp", "description": "If applicable, the Brand name ‘Doing Business As (DBA)’.\n" }, "terms_and_conditions_url": { "type": "string", "maxLength": 500, "example": "https://www.vonage.com/legal/messaging-service-supplementary-terms/", "description": "Provide Terms link for the company/organization. Must be a valid URL.\n" }, "privacy_policy_url": { "type": "string", "maxLength": 500, "example": "https://www.vonage.com/legal/privacy-policy/", "description": "Provide a Privacy Policy link for the company/organization. Must be a valid URL.\n" }, "entity_type": { "$ref": "#/components/schemas/EntityType" }, "tax_id_type": { "$ref": "#/components/schemas/TaxIDType" }, "tax_id": { "$ref": "#/components/schemas/TaxID" }, "tax_id_issuing_country": { "$ref": "#/components/schemas/TaxIDIssuingCountry" } } }, "MonthlyVolume": { "type": "string", "enum": [ "10", "100", "1,000", "10,000", "100,000", "250,000", "500,000", "750,000", "1,000,000", "5,000,000", "10,000,000+" ], "example": "10,000", "description": "Estimated monthly message volume." }, "ISVResellerInfo": { "type": "object", "title": "ISV/Reseller", "description": "ISV/Reseller initiating the registration on behalf of the customer.\n\nNote: This is only required for ISV and resellers.\n", "properties": { "name": { "type": "string", "maxLength": 500, "description": "If you are an ISV/Reseller, enter the name of your business.", "example": "Reseller ABC" }, "contact_email": { "type": "string", "description": "Vonage will only communicate with this email address for ISV/Reseller submissions. Must be a valid email.\n", "maxLength": 500, "example": "john.doe@resellerabc.com" } } }, "TFN": { "type": "string", "format": "e164", "title": "TFN Phone number", "description": "Must be a valid purchased TFN in E.164 international format without the + prefix. Should always start with prefix 1800, 1888, 1877, 1866, 1855, 1844, or 1833.\n", "example": "18001234567", "minLength": 11, "maxLength": 11 }, "BusinessReason": { "type": "string", "title": "Additional information for managing a business associated with a specific number.", "description": "This field is required when multiple numbers are included in the registration. Provide a clear reason for each number to get multiple numbers verified for messaging services.", "maxLength": 149, "example": "Two numbers are for two sales regions, one number per region to manage and track the business (East and West)" }, "RequestedNumbers": { "type": "array", "description": "List all toll-free phone numbers to be registered. Add up to 5 TFNs.\n", "maxItems": 5, "items": { "type": "object", "required": [ "number" ], "properties": { "number": { "$ref": "#/components/schemas/TFN" }, "business_reason": { "$ref": "#/components/schemas/BusinessReason" } } } }, "UseCaseCategory": { "type": "string", "title": "Use case category", "description": "Use case category that represents your business industry; choose “Mixed” if marketing and alerts.\n", "enum": [ "2FA", "App Notifications", "Appointments", "Auctions", "Auto / Dealership Services", "Banking", "Billing", "Booking Confirmations", "Business Updates", "COVID-19 Alerts", "Career Training", "Chatbot", "Conversational / Alerts", "Courier Services & Deliveries", "Educational", "Emergency Alerts", "Employee Alerts / Notifications", "Events & Planning", "Financial Services", "Fraud Alerts", "Fundraising", "General Marketing", "HR / Staffing", "Healthcare", "Housing Community Updates", "Insurance Services", "Job Alerts", "Legal Services", "Mixed", "Motivational Reminders", "Notary Notifications", "Notifications", "Order Notifications", "Political", "Public Works", "Real Estate Services", "Receipt Notifications", "Religious Services", "Repair and Diagnostics Alerts", "Rewards Program", "Surveys", "System Alerts", "Waitlist Alerts", "Webinar Reminders", "Workshop Alerts" ], "example": "Political" }, "UseCaseDescription": { "type": "string", "maxLength": 500, "title": "Use case description", "description": "Describe the business reason for the selected use case, and enter any other important information about this request.\n", "example": "This Toll-Free Number will be used to deliver opt-in SMS communications, such as one-time passwords (OTPs), alerts, and notifications, to end users who have provided explicit consent." }, "CampaignVerifyAuthToken": { "type": "string", "maxLength": 500, "title": "Campaign Verify Authorization Token", "description": "Note: This field is required only when the use_case category is set to \"Political\".\n\nIf you do not have a token, visit Campaign Verify at https://www.campaignverify.org/ to get started.\nA valid token follows a specific, pipe-delimited format, comprised of six fields:\ncv|1.0|mno|tfree|UUID|SecretString\n- cv: A constant prefix indicating a Campaign Verify token.\n- 1.0: The token version number (currently 1.0).\n- mno: The Service ID for Toll-Free numbers (for 10DLC, this would be tcr).\n- tfree: The Channel ID for Toll-Free.\n- UUID: A unique identifier specific to your verified committee/brand.\n- SecretString: A unique, 32-bit URL-safe random string.\n", "example": "cv|1.0|mno|tfree|9957c339-d46f-49b7-a399-2e6d5ebac66d|GQ3NMEjED8xSlaAgR" }, "CampaignVerifyExpiryDate": { "type": "string", "nullable": true, "format": "date-time", "title": "Campaign Verify Expiry Date", "description": "The expiration date of the Campaign Verify token. This field is applicable only to Political use cases. New tokens typically remain valid for 2 years from the date of issue.\n" }, "UseCase": { "type": "object", "title": "Use case", "description": "Describes the use case.\n", "required": [ "category", "description" ], "properties": { "category": { "$ref": "#/components/schemas/UseCaseCategory" }, "description": { "$ref": "#/components/schemas/UseCaseDescription" }, "campaign_verify_auth_token": { "$ref": "#/components/schemas/CampaignVerifyAuthToken" }, "campaign_verify_expiry_date": { "allOf": [ { "$ref": "#/components/schemas/CampaignVerifyExpiryDate" } ], "readOnly": true } } }, "MessageContent": { "type": "string", "maxLength": 1000, "title": "Message content", "description": "Provide an example of a message to be sent, up to 1000 characters.\n", "example": "[Candidate/Org Name]: You’re invited to a community meeting on [Date] at [Location]. RSVP here: [URL]. Message frequency varies. Reply STOP to end." }, "AgeGated": { "type": "boolean", "nullable": true, "title": "Age Gated Content", "description": "Select 'true' if your messages include content that is legally restricted to certain age groups over 21 years of age (e.g., alcohol, gambling, adult content).\n\nOn your website:\n1. Provide the end user's birth date (MM/DD/YYYY) to receive promotional/alert messages.\n2. On the bottom, add instructions that \"If a user is too young to purchase, then place a hold on sending messages until age appropriate.\"\n\nOn end user's mobile device:\n1. Double Opt-In age gate text message flow includes a Birthdate entry field\nEnd user receives opt-in message from an online/mobile site. Example: [Brand Name]: Welcome! Reply with your \"birthdate\" (MM/DD/YYYY) to successfully sign-up for promotional/alerts messages from _____ (content provider name). Reply STOP to cancel.\nEnd user sends message in this format - MM/DD/YYYY -\nIf user replies with age of 21+ then add to opt-in list and send opt-in confirmation message. Example: [Brand Name]: Welcome! Msg frequency varies. Msg & data rates may apply. For support, reply HELP for STOP to cancel.\n", "default": false, "example": false }, "MessageContentObject": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/MessageContent" }, "age_gated": { "$ref": "#/components/schemas/AgeGated" } } }, "OptInWorkflow": { "type": "string", "enum": [ "Online (website, Mobile app/browser)", "Text-to-join", "Point of sale", "Other" ], "example": "Other", "description": "Select consent method collected from the message recipient.\n" }, "OptInWorkflowDescription": { "type": "string", "maxLength": 494, "title": "OptIn description", "description": "Note: This field is required only when the workflow is set to \"Other\".\n\nDescribe the opt-in process where consent is collected from the message recipient.\n", "example": "Paper-based opt-in form: End-customer consent may be obtained via a paper form. The form requires the end user to enter their mobile phone number and affirmatively select a consent checkbox stating “I agree to receive text messages.” The signed and completed form constitutes valid opt-in documentation." }, "OptInImages": { "type": "array", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "OptIn image URL", "description": "- Provide a shared link or publicly accessible link to a screenshot\n- Do not add any additional content, i.e. \"here's a list\"\n" } } }, "example": [ { "url": "https://drive.google.com/file/d/screenshot1/view" }, { "url": "https://drive.google.com/file/d/screenshot2/view" } ] }, "OptInKeywords": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "title": "Opt-In Keywords", "description": "Provide one or more opt-in keywords that trigger an auto-response message to the recipient.\n", "example": [ "JOIN", "START", "YES" ] }, "OptInMessage": { "type": "string", "maxLength": 160, "title": "Opt-In Confirmation Message", "description": "The opt-in message responds to the recipient with your brand name, welcome, use case category and helpful hints.\n\nNote: SMS response message is limited to 160 characters for compliance purposes.\n", "example": "[Vonage]: Welcome! You've signed up for alert messages. Msg freq varies. Msg&data rates may apply. Reply HELP for info, STOP to opt-out." }, "HelpMessage": { "type": "string", "maxLength": 160, "title": "Help Confirmation Message", "description": "The HELP keyword confirmation message sent to a user should contain your Brand name and two (2) contact methods, such as a toll-free number, email address or a link to a customer support page.\n\nNote: SMS response message is limited to 160 characters for compliance purposes.\n", "example": "[Vonage]: Thanks for contacting us. Please visit https://www.vonage.com/support or email support@api.vonage.com" }, "OptIn": { "type": "object", "required": [ "workflow", "images" ], "properties": { "workflow": { "$ref": "#/components/schemas/OptInWorkflow" }, "workflow_description": { "$ref": "#/components/schemas/OptInWorkflowDescription" }, "images": { "$ref": "#/components/schemas/OptInImages" }, "keywords": { "$ref": "#/components/schemas/OptInKeywords" }, "confirmation_message": { "$ref": "#/components/schemas/OptInMessage" }, "help_message": { "$ref": "#/components/schemas/HelpMessage" } } }, "AdditionalInformation": { "type": "string", "maxLength": 350, "title": "Additional information", "description": "Provide any additional information.\n", "example": "This is test additional information." }, "SubmissionStatus": { "type": "string", "title": "Submission status", "description": "The submission status of the registration.\n", "enum": [ "SUBMITTED", "DRAFT" ] }, "CreateRegistrationRequest": { "type": "object", "required": [ "business", "estimated_monthly_volume", "requested_numbers", "use_case", "message_content", "additional_information", "opt_in" ], "properties": { "business": { "$ref": "#/components/schemas/BusinessInfo" }, "estimated_monthly_volume": { "$ref": "#/components/schemas/MonthlyVolume" }, "isv_reseller": { "$ref": "#/components/schemas/ISVResellerInfo" }, "requested_numbers": { "$ref": "#/components/schemas/RequestedNumbers" }, "use_case": { "$ref": "#/components/schemas/UseCase" }, "message_content": { "$ref": "#/components/schemas/MessageContentObject" }, "opt_in": { "$ref": "#/components/schemas/OptIn" }, "additional_information": { "$ref": "#/components/schemas/AdditionalInformation" }, "status": { "$ref": "#/components/schemas/SubmissionStatus" } } }, "RegistrationID": { "title": "Unique identifier of a registration", "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "description": "Unique identifier of a registration" }, "CreateRegistrationResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RegistrationID" } } }, "instance": { "description": "Instance ID", "type": "string", "example": "797a8f199c45014ab7b08bfe9cc1c12c" }, "CommonError": { "description": "General error schema", "type": "object", "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#TO_BE_UPDATED" }, "title": { "type": "string", "example": "Error title" }, "detail": { "type": "string", "example": "Detailed error message" }, "instance": { "$ref": "#/components/schemas/instance" } } }, "NumberStatus": { "title": "TFN verification status", "description": "The verification status of the tfn.\n", "type": "string", "enum": [ "UPDATES_REQUIRED", "PENDING_REVIEW", "CARRIERS_REVIEW", "REGISTERED", "REJECTED", "DRAFT", "BLOCKED" ] }, "RejectedReason": { "title": "Reason for rejected tfn number registration", "description": "Reason the number is rejected for tfn registration", "type": "string", "nullable": true, "example": "DisallowedContent - Gambling" }, "RequestedNumbersDetails": { "type": "array", "description": "TFN number details", "items": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TFN" }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "rejected_reason": { "$ref": "#/components/schemas/RejectedReason" }, "business_reason": { "$ref": "#/components/schemas/BusinessReason" } } } }, "CreationDate": { "type": "string", "description": "The date and time of creation.", "format": "date-time" }, "UpdateDate": { "type": "string", "description": "The date and time of last update.", "format": "date-time" }, "SubmissionDate": { "type": "string", "nullable": true, "description": "The date and time of submission.", "format": "date-time" }, "GetRegistrationResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RegistrationID" }, "business": { "$ref": "#/components/schemas/BusinessInfo" }, "isv_reseller": { "$ref": "#/components/schemas/ISVResellerInfo" }, "estimated_monthly_volume": { "$ref": "#/components/schemas/MonthlyVolume" }, "requested_numbers": { "$ref": "#/components/schemas/RequestedNumbersDetails" }, "use_case": { "$ref": "#/components/schemas/UseCase" }, "message_content": { "$ref": "#/components/schemas/MessageContentObject" }, "opt_in": { "$ref": "#/components/schemas/OptIn" }, "additional_information": { "$ref": "#/components/schemas/AdditionalInformation" }, "status": { "$ref": "#/components/schemas/SubmissionStatus" }, "creation_date": { "$ref": "#/components/schemas/CreationDate" }, "last_update_date": { "$ref": "#/components/schemas/UpdateDate" }, "submission_date": { "$ref": "#/components/schemas/SubmissionDate" } } }, "UpdateRegistrationRequest": { "type": "object", "properties": { "business": { "$ref": "#/components/schemas/BusinessInfo" }, "isv_reseller": { "$ref": "#/components/schemas/ISVResellerInfo" }, "estimated_monthly_volume": { "$ref": "#/components/schemas/MonthlyVolume" }, "requested_numbers": { "$ref": "#/components/schemas/RequestedNumbers" }, "use_case": { "$ref": "#/components/schemas/UseCase" }, "message_content": { "$ref": "#/components/schemas/MessageContentObject" }, "opt_in": { "$ref": "#/components/schemas/OptIn" }, "additional_information": { "$ref": "#/components/schemas/AdditionalInformation" }, "status": { "type": "string", "title": "Submission status", "description": "Set to `SUBMITTED` to submit `DRAFT` registration. If omitted, the previous status is maintained.\n", "enum": [ "SUBMITTED" ] } } }, "ReviewReason": { "title": "Reason for the given status of TFN", "description": "Reason for the given status of TFN. The reason will be empty for statuses like REGISTERED or PENDING_REVIEW.", "type": "string", "example": "The provided use case description is insufficient. Please provide more details." }, "GetEventsResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/RegistrationID" }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "reason": { "$ref": "#/components/schemas/ReviewReason" }, "created_at": { "$ref": "#/components/schemas/CreationDate" } } }, "PaginatedSelfResponse": { "type": "object", "properties": { "page_size": { "type": "integer", "example": 10 }, "_links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://example:com/resource?page_size=10&cursor=19284743" } } } } }, "NumberRegistrationsResponse": { "type": "object", "properties": { "number": { "$ref": "#/components/schemas/TFN" }, "status": { "$ref": "#/components/schemas/NumberStatus" }, "business_name": { "$ref": "#/components/schemas/BusinessName" }, "registration_id": { "$ref": "#/components/schemas/RegistrationID" }, "submission_date": { "$ref": "#/components/schemas/SubmissionDate" }, "status_change_date": { "type": "string", "format": "date-time", "description": "Date when the current status tfn was updated" } } }, "PaginatedResponse": { "type": "object", "properties": { "page_size": { "type": "integer", "example": 10 }, "_links": { "type": "object", "properties": { "self": { "type": "string", "example": "https://example:com/resource?page_size=10&cursor=19284743" }, "next": { "type": "string", "example": "https://example:com/resource?page_size=10&cursor=19284743" }, "prev": { "type": "string", "example": "https://example:com/resource?page_size=10&cursor=19284743" }, "first": { "type": "string", "example": "https://example:com/resource?page_size=10" } } } } } }, "responses": { "BadRequestError": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonError" }, "example": { "type": "https://developer.vonage.com/api-errors#invalid-json", "title": "Invalid request body", "detail": "The request body did not contain valid JSON", "instance": "797a8f199c45014ab7b08bfe9cc1c12c" } } } }, "BadCredentialsError": { "description": "Credential is missing or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonError" }, "example": { "type": "https://developer.vonage.com/api-errors#unauthorized", "title": "Invalid credentials supplied", "detail": "You did not provide correct credentials.", "instance": "797a8f199c45014ab7b08bfe9cc1c12c" } } } }, "NotFoundError": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonError" }, "example": { "type": "https://developer.vonage.com/api-errors#not-found", "title": "Not Found", "detail": "ID 'ABC123' does not exist, or you do not have access", "instance": "797a8f199c45014ab7b08bfe9cc1c12c" } } } }, "UnprocessableResourceError": { "description": "Resource Unprocessable", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "instance": { "description": "Request id", "type": "string", "example": "797a8f199c45014ab7b08bfe9cc1c12c" }, "invalid_parameters": { "type": "array", "title": "Invalid parameters", "description": "List the parameters with invalid data and the reason why the validation failed.\n", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the parameter that had a data issue" }, "reason": { "type": "string", "description": "Reason why the validation failed" } } } } } }, "example": { "type": "https://developer.vonage.com/api-errors#invalid", "title": "There were some issues with the submitted data", "detail": "There were some errors submitting your data, please correct the requested fields", "instance": "3c2548d132ca4b09870da17d56969a75", "invalid_parameters": [ { "name": "phone_number", "reason": "phone_number must be a valid E.164 phone number" }, { "name": "business_name", "reason": "business_name is required" } ] } } } }, "ThrottledError": { "description": "Too many requests", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#throttled" }, "title": { "type": "string", "example": "Too many requests" }, "detail": { "type": "string", "example": "Your account has reached it's API limit and has been throttled" }, "instance": { "$ref": "#/components/schemas/instance" }, "retry_after": { "description": "Time in seconds the client should wait before sending a new request", "type": "integer", "example": 30 } } } } } } }, "parameters": { "pathRegistrationID": { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/RegistrationID" } }, "pathTFN": { "name": "number", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/TFN" } }, "Cursor": { "in": "query", "name": "cursor", "description": "Cursor for pagination", "required": false, "schema": { "type": "string", "example": 19284743 } }, "PageSize": { "in": "query", "name": "page_size", "description": "Number of results per page", "required": false, "schema": { "type": "integer", "example": 10 } } } } }