{ "openapi": "3.0.3", "info": { "title": "Address API", "version": "1.0.0", "description": "The Address API lets you create and modify Addresses in Vonage. These addresses may be linked to numbers\n\nMore details at https://developer.vonage.com/\n", "termsOfService": "https://www.vonage.com/legal/communications-apis/terms-of-use/", "contact": { "name": "Vonage Developer Relations", "email": "devrel@vonage.com", "url": "https://developer.vonage.com/" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "https://api.nexmo.com/v1/addresses", "description": "Server URL" } ], "tags": [ { "name": "Addresses", "description": "Create and modify Addresses in Vonage." } ], "paths": { "/": { "get": { "security": [ { "basicAuth": [] } ], "tags": [ "Addresses" ], "summary": "Get details of your configured Addresses", "description": "Get details of your configured Addresses", "operationId": "getAddresses", "parameters": [ { "name": "page", "in": "query", "description": "Page index", "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "page_size", "in": "query", "description": "Number of records per page", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressList" } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "429": { "$ref": "#/components/responses/ThrottledError" } } }, "post": { "security": [ { "basicAuth": [] } ], "tags": [ "Addresses" ], "summary": "Create a new Address", "description": "Create a new Address", "operationId": "createAddress", "requestBody": { "description": "Create a new Address", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AddressObject" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionedAddressObject" } } } }, "400": { "$ref": "#/components/responses/ErrorInvalidAddress" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "429": { "$ref": "#/components/responses/ThrottledError" } } } }, "/{id}": { "get": { "security": [ { "basicAuth": [] } ], "tags": [ "Addresses" ], "summary": "Get details of an Address", "description": "Get details of an Address", "operationId": "getAddress", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Filter by address id", "schema": { "type": "string", "example": "c49f3586-9b3b-458b-89fc-3c8beb58865c" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionedAddressObject" } } } }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/ThrottledError" } } }, "delete": { "security": [ { "basicAuth": [] } ], "tags": [ "Addresses" ], "summary": "Delete an Address", "description": "Delete an Address", "operationId": "deleteAddress", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Filter by address id", "schema": { "type": "string", "example": "c49f3586-9b3b-458b-89fc-3c8beb58865c" } } ], "responses": { "204": { "description": "Deleted" }, "400": { "$ref": "#/components/responses/ErrorInvalidAddressId" }, "401": { "$ref": "#/components/responses/BadCredentialsError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ErrorAddressUsedByNumber" }, "429": { "$ref": "#/components/responses/ThrottledError" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "schemas": { "AddressList": { "title": "Address List", "type": "object", "properties": { "page_size": { "example": 100 }, "page": { "example": 3 }, "total_pages": { "example": 15 }, "total_items": { "example": 1450 }, "_embedded": { "description": "A list of Address objects. ", "type": "object", "properties": { "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/ProvisionedAddressObject" } } } } } }, "id": { "title": "Address ID", "type": "string", "example": "c49f3586-9b3b-458b-89fc-3c8beb58865c", "description": "Vonage Address unique ID" }, "address_name": { "title": "Address friendly name", "type": "string", "example": "myaddress", "minLength": 2, "maxLength": 32, "description": "A friendly name to identify the address" }, "address_line1": { "title": "Address line 1", "type": "string", "example": "1 REGAL CT", "description": "First line of the full address" }, "address_line2": { "title": "Address line 2", "type": "string", "example": "Merchant's House 205", "description": "Second line of the full address" }, "city": { "title": "City", "type": "string", "example": "New York", "description": "The city where this address is located" }, "region": { "title": "State or region", "type": "string", "example": "NJ", "description": "The state or region of the address" }, "address_type": { "title": "Type of address", "type": "string", "enum": [ "emergency" ], "example": "emergency", "description": "Type of address" }, "address_location_type": { "title": "Address Location type", "type": "string", "enum": [ "business", "residential" ], "example": "business", "default": "business", "description": "Addrss location type as a business or domestic" }, "postal_code": { "title": "Postal Code / Zip Code", "type": "string", "example": "10002", "description": "The Postal Code of this address" }, "country": { "title": "Country", "type": "string", "minLength": 2, "maxLength": 2, "example": "US", "description": "The two character country code in ISO 3166-1 alpha-2 format" }, "ProvisionedAddressObject": { "title": "Address", "type": "object", "properties": { "id": { "$ref": "#/components/schemas/id" }, "address_name": { "$ref": "#/components/schemas/address_name" }, "address_line1": { "$ref": "#/components/schemas/address_line1" }, "address_line2": { "$ref": "#/components/schemas/address_line2" }, "city": { "$ref": "#/components/schemas/city" }, "region": { "$ref": "#/components/schemas/region" }, "type": { "$ref": "#/components/schemas/address_type" }, "address_location_type": { "$ref": "#/components/schemas/address_location_type" }, "postal_code": { "$ref": "#/components/schemas/postal_code" }, "country": { "$ref": "#/components/schemas/country" } } }, "instance": { "description": "Instance ID", "type": "string", "example": "797a8f199c45014ab7b08bfe9cc1c12c" }, "AddressObject": { "title": "Address", "type": "object", "properties": { "address_name": { "$ref": "#/components/schemas/address_name" }, "address_line1": { "$ref": "#/components/schemas/address_line1" }, "address_line2": { "$ref": "#/components/schemas/address_line2" }, "city": { "$ref": "#/components/schemas/city" }, "region": { "$ref": "#/components/schemas/region" }, "type": { "$ref": "#/components/schemas/address_type" }, "address_location_type": { "$ref": "#/components/schemas/address_location_type" }, "postal_code": { "$ref": "#/components/schemas/postal_code" }, "country": { "$ref": "#/components/schemas/country" } } } }, "responses": { "ErrorInvalidAddress": { "description": "Invalid address for emergency services", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errorsinvalid-address" }, "title": { "type": "string", "enum": [ "Invalid address for emergency services" ], "example": "Invalid address for emergency services" }, "detail": { "type": "string", "enum": [ "Emergency services can't be activated on invalid addresses. If address is correct contact Support." ], "example": "Emergency services can't be activated on invalid addresses. If address is correct contact Support." }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "ErrorAddressUsedByNumber": { "description": "Emergency address is in use", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#address-in-use" }, "title": { "type": "string", "enum": [ "Emergency address is in use" ], "example": "Emergency address is in use" }, "detail": { "type": "string", "enum": [ "The emergency address is in use by a number and can't be modified or deleted" ], "example": "The emergency address is in use by a number and can't be modified or deleted" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "ErrorInvalidAddressId": { "description": "Invalid emergency address Id", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#invalid-address-id" }, "title": { "type": "string", "example": "Invalid emergency address Id" }, "detail": { "type": "string", "example": "Invalid emergency address Id" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "BadCredentialsError": { "description": "Credential is missing or invalid", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#unauthorized" }, "title": { "type": "string", "example": "Invalid credentials supplied" }, "detail": { "type": "string", "example": "You did not provide correct credentials." }, "instance": { "$ref": "#/components/schemas/instance" } } } } } }, "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 } } } } } }, "NotFoundError": { "description": "Resource Not Found", "content": { "application/json": { "schema": { "properties": { "type": { "type": "string", "example": "https://developer.vonage.com/api-errors#not-found" }, "title": { "type": "string", "example": "Not Found" }, "detail": { "type": "string", "example": "ID 'ABC123' does not exist, or you do not have access" }, "instance": { "$ref": "#/components/schemas/instance" } } } } } } } } }