{ "openapi": "3.0.3", "info": { "title": "DIDWW Public API", "version": "2026-04-16", "description": "JSONAPI interface to the DIDWW platform: browse coverage, order and manage DIDs,\nroute them to voice trunks, and reserve numbers before purchase.\n\nEvery request is authenticated with an `api-key` header. Versions are selected\nper request with the `X-DIDWW-Api-Version` header, defaulting to the\nversion configured for the API key's customer; this document describes\n`2026-04-16`.\n\nResponse schemas describe the full resource. A request narrowing one with\n`fields[...]` receives fewer members than its schema lists, deliberately:\nOpenAPI cannot express a member that is required only until a query\nparameter prunes it.\n", "contact": { "name": "DIDWW Support", "email": "support@didww.com" } }, "externalDocs": { "description": "DIDWW API documentation", "url": "https://doc.didww.com/api3/2026-04-16/" }, "tags": [ { "name": "Coverage", "description": "Countries, regions, cities and areas DIDWW sells numbers in." }, { "name": "DID groups", "description": "Groups of numbers sharing a price and a set of capabilities, and the individual numbers available within them." }, { "name": "DID reservations", "description": "Short-lived holds that keep a number available while an order is prepared." }, { "name": "Orders", "description": "Purchases of numbers and of channel capacity." }, { "name": "DIDs", "description": "The numbers the account owns, and how each one is routed." }, { "name": "Account", "description": "Balance, the ownership history of a number, and the export jobs that deliver call detail records." }, { "name": "Capacity", "description": "Channel pools and the shared capacity groups that draw on them." }, { "name": "Inbound trunks", "description": "Where inbound calls are delivered, the groups that spread them over several destinations, and the points of presence a trunk can be pinned to." }, { "name": "Outbound trunks", "description": "Outbound calling: credentials, allowed sources and the default number presented to the called party." }, { "name": "Regulation", "description": "Identities, addresses and documents. Many countries release a number only once the paperwork behind it has been approved." }, { "name": "Address verifications", "description": "Submissions of an identity and an address for approval against the requirements of a number." }, { "name": "Emergency", "description": "Emergency calling: what a country requires, validating a submission against it, and the service that results." } ], "servers": [ { "url": "https://api.didww.com/v3", "description": "Production" }, { "url": "https://sandbox-api.didww.com/v3", "description": "Sandbox" } ], "components": { "securitySchemes": { "api_key": { "type": "apiKey", "name": "api-key", "in": "header", "description": "API key issued to the customer in the DIDWW user panel." } }, "schemas": { "Meta": { "type": "object", "required": [ "api_version" ], "properties": { "api_version": { "type": "string", "description": "V3 API version that served the request.", "example": "2026-04-16" } } }, "CollectionMeta": { "type": "object", "required": [ "api_version", "total_records" ], "properties": { "api_version": { "type": "string", "description": "V3 API version that served the request.", "example": "2026-04-16" }, "total_records": { "type": "integer", "description": "Total number of records matching the request." } } }, "RelationshipLinks": { "type": "object", "required": [ "self", "related" ], "properties": { "self": { "type": "string", "format": "uri", "description": "Relationship linkage endpoint. Not routed for the emergency types." }, "related": { "type": "string", "format": "uri", "description": "Related resource endpoint. Not routed for the emergency types." } } }, "PaginationLinks": { "type": "object", "description": "Pagination links. `next` / `prev` are omitted at the respective ends of the collection.", "required": [ "first", "last" ], "properties": { "first": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "required": [ "title", "detail", "code", "status" ], "properties": { "title": { "type": "string", "example": "Filter not allowed" }, "detail": { "type": "string", "example": "bogus is not allowed." }, "code": { "type": "string", "description": "JSONAPI error code. Not an HTTP status: `100` is a validation error, `102` a disallowed filter, `106` a missing parameter, and so on.", "example": "102" }, "status": { "type": "string", "description": "HTTP status as a string.", "example": "400" }, "source": { "type": "object", "description": "Points at the part of the request that caused the error. Present on validation errors.", "required": [ "pointer" ], "properties": { "pointer": { "type": "string", "example": "/data/attributes/capacity_limit" } } }, "meta": { "type": "object", "description": "Error-specific details. Carried by a few errors (e.g. insufficient balance)." } } }, "ErrorsDocument": { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "AddressIdentifier": { "type": "object", "description": "Identifier of an `addresses` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "addresses" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "AddressIdentifierNullable": { "type": "object", "description": "Identifier of an `addresses` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "addresses" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "AddressRequirementIdentifier": { "type": "object", "description": "Identifier of an `address_requirements` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "address_requirements" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "AddressRequirementIdentifierNullable": { "type": "object", "description": "Identifier of an `address_requirements` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "address_requirements" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "AddressRequirementToOne": { "type": "object", "description": "Relationship to an `address_requirements` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/AddressRequirementIdentifierNullable" } } }, "AddressToMany": { "type": "object", "description": "Relationship to an `addresses` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressIdentifier" } } } }, "AddressToOne": { "type": "object", "description": "Relationship to an `addresses` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/AddressIdentifierNullable" } } }, "AddressVerificationIdentifierNullable": { "type": "object", "description": "Identifier of an `address_verifications` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "address_verifications" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "AddressVerificationToOne": { "type": "object", "description": "Relationship to an `address_verifications` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/AddressVerificationIdentifierNullable" } } }, "AreaIdentifierNullable": { "type": "object", "description": "Identifier of an `areas` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "areas" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "AreaToOne": { "type": "object", "description": "Relationship to an `areas` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/AreaIdentifierNullable" } } }, "AvailableDidIdentifier": { "type": "object", "description": "Identifier of an `available_dids` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "available_dids" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "AvailableDidIdentifierNullable": { "type": "object", "description": "Identifier of an `available_dids` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "available_dids" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "AvailableDidToOne": { "type": "object", "description": "Relationship to an `available_dids` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/AvailableDidIdentifierNullable" } } }, "CapacityPoolIdentifier": { "type": "object", "description": "Identifier of a `capacity_pools` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "capacity_pools" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "CapacityPoolIdentifierNullable": { "type": "object", "description": "Identifier of a `capacity_pools` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "capacity_pools" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "CapacityPoolToOne": { "type": "object", "description": "Relationship to a `capacity_pools` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/CapacityPoolIdentifierNullable" } } }, "CityIdentifierNullable": { "type": "object", "description": "Identifier of a `cities` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "cities" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "CityToOne": { "type": "object", "description": "Relationship to a `cities` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/CityIdentifierNullable" } } }, "CountryIdentifier": { "type": "object", "description": "Identifier of a `countries` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "countries" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "CountryIdentifierNullable": { "type": "object", "description": "Identifier of a `countries` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "countries" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "CountryToMany": { "type": "object", "description": "Relationship to a `countries` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CountryIdentifier" } } } }, "CountryToOne": { "type": "object", "description": "Relationship to a `countries` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/CountryIdentifierNullable" } } }, "DidGroupIdentifierNullable": { "type": "object", "description": "Identifier of a `did_groups` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "did_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "DidGroupToOne": { "type": "object", "description": "Relationship to a `did_groups` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/DidGroupIdentifierNullable" } } }, "DidGroupTypeIdentifierNullable": { "type": "object", "description": "Identifier of a `did_group_types` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "did_group_types" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "DidGroupTypeToOne": { "type": "object", "description": "Relationship to a `did_group_types` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/DidGroupTypeIdentifierNullable" } } }, "DidIdentifier": { "type": "object", "description": "Identifier of a `dids` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "dids" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "DidIdentifierNullable": { "type": "object", "description": "Identifier of a `dids` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "dids" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "DidToMany": { "type": "object", "description": "Relationship to a `dids` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DidIdentifier" } } } }, "EmergencyCallingServiceIdentifier": { "type": "object", "description": "Identifier of an `emergency_calling_services` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "emergency_calling_services" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "EmergencyCallingServiceIdentifierNullable": { "type": "object", "description": "Identifier of an `emergency_calling_services` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "emergency_calling_services" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "EmergencyCallingServiceToOne": { "type": "object", "description": "Relationship to an `emergency_calling_services` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/EmergencyCallingServiceIdentifierNullable" } } }, "EmergencyRequirementIdentifier": { "type": "object", "description": "Identifier of an `emergency_requirements` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "emergency_requirements" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "EmergencyRequirementIdentifierNullable": { "type": "object", "description": "Identifier of an `emergency_requirements` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "emergency_requirements" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "EmergencyRequirementToOne": { "type": "object", "description": "Relationship to an `emergency_requirements` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/EmergencyRequirementIdentifierNullable" } } }, "EmergencyVerificationIdentifierNullable": { "type": "object", "description": "Identifier of an `emergency_verifications` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "emergency_verifications" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "EmergencyVerificationToOne": { "type": "object", "description": "Relationship to an `emergency_verifications` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/EmergencyVerificationIdentifierNullable" } } }, "EncryptedFileIdentifier": { "type": "object", "description": "Identifier of an `encrypted_files` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "encrypted_files" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "IdentityIdentifier": { "type": "object", "description": "Identifier of an `identities` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "identities" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "IdentityIdentifierNullable": { "type": "object", "description": "Identifier of an `identities` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "identities" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "IdentityToOne": { "type": "object", "description": "Relationship to an `identities` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/IdentityIdentifierNullable" } } }, "NanpaPrefixIdentifierNullable": { "type": "object", "description": "Identifier of a `nanpa_prefixes` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "nanpa_prefixes" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "NanpaPrefixToOne": { "type": "object", "description": "Relationship to a `nanpa_prefixes` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/NanpaPrefixIdentifierNullable" } } }, "OrderIdentifierNullable": { "type": "object", "description": "Identifier of an `orders` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "orders" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "OrderToOne": { "type": "object", "description": "Relationship to an `orders` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/OrderIdentifierNullable" } } }, "PermanentSupportingDocumentIdentifier": { "type": "object", "description": "Identifier of a `permanent_supporting_documents` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "permanent_supporting_documents" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "PermanentSupportingDocumentToMany": { "type": "object", "description": "Relationship to a `permanent_supporting_documents` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PermanentSupportingDocumentIdentifier" } } } }, "PopIdentifierNullable": { "type": "object", "description": "Identifier of a `pops` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "pops" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "PopToOne": { "type": "object", "description": "Relationship to a `pops` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/PopIdentifierNullable" } } }, "ProofEntityIdentifier": { "type": "object", "description": "Identifier of an `identities` or `addresses` resource.", "oneOf": [ { "$ref": "#/components/schemas/IdentityIdentifier" }, { "$ref": "#/components/schemas/AddressIdentifier" } ], "discriminator": { "propertyName": "type", "mapping": { "identities": "#/components/schemas/IdentityIdentifier", "addresses": "#/components/schemas/AddressIdentifier" } } }, "ProofEntityIdentifierNullable": { "type": "object", "description": "Identifier of an `identities` or `addresses` resource. `null` when nothing is related.", "oneOf": [ { "$ref": "#/components/schemas/IdentityIdentifier" }, { "$ref": "#/components/schemas/AddressIdentifier" } ], "discriminator": { "propertyName": "type", "mapping": { "identities": "#/components/schemas/IdentityIdentifier", "addresses": "#/components/schemas/AddressIdentifier" } }, "nullable": true }, "ProofEntityToOne": { "type": "object", "description": "Relationship to an `identities` or `addresses` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/ProofEntityIdentifierNullable" } } }, "ProofIdentifier": { "type": "object", "description": "Identifier of a `proofs` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "proofs" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "ProofToMany": { "type": "object", "description": "Relationship to a `proofs` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProofIdentifier" } } } }, "ProofTypeIdentifier": { "type": "object", "description": "Identifier of a `proof_types` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "proof_types" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "ProofTypeIdentifierNullable": { "type": "object", "description": "Identifier of a `proof_types` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "proof_types" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "ProofTypeToMany": { "type": "object", "description": "Relationship to a `proof_types` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProofTypeIdentifier" } } } }, "ProofTypeToOne": { "type": "object", "description": "Relationship to a `proof_types` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/ProofTypeIdentifierNullable" } } }, "QtyBasedPricingIdentifier": { "type": "object", "description": "Identifier of a `qty_based_pricings` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "qty_based_pricings" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "QtyBasedPricingToMany": { "type": "object", "description": "Relationship to a `qty_based_pricings` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/QtyBasedPricingIdentifier" } } } }, "RegionIdentifier": { "type": "object", "description": "Identifier of a `regions` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "regions" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "RegionIdentifierNullable": { "type": "object", "description": "Identifier of a `regions` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "regions" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "RegionToMany": { "type": "object", "description": "Relationship to a `regions` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RegionIdentifier" } } } }, "RegionToOne": { "type": "object", "description": "Relationship to a `regions` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/RegionIdentifierNullable" } } }, "SharedCapacityGroupIdentifier": { "type": "object", "description": "Identifier of a `shared_capacity_groups` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "shared_capacity_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "SharedCapacityGroupIdentifierNullable": { "type": "object", "description": "Identifier of a `shared_capacity_groups` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "shared_capacity_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "SharedCapacityGroupToMany": { "type": "object", "description": "Relationship to a `shared_capacity_groups` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SharedCapacityGroupIdentifier" } } } }, "SharedCapacityGroupToOne": { "type": "object", "description": "Relationship to a `shared_capacity_groups` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/SharedCapacityGroupIdentifierNullable" } } }, "StockKeepingUnitIdentifier": { "type": "object", "description": "Identifier of a `stock_keeping_units` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "stock_keeping_units" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "StockKeepingUnitToMany": { "type": "object", "description": "Relationship to a `stock_keeping_units` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockKeepingUnitIdentifier" } } } }, "SupportingDocumentTemplateIdentifier": { "type": "object", "description": "Identifier of a `supporting_document_templates` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "supporting_document_templates" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "SupportingDocumentTemplateIdentifierNullable": { "type": "object", "description": "Identifier of a `supporting_document_templates` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "supporting_document_templates" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "SupportingDocumentTemplateToOne": { "type": "object", "description": "Relationship to a `supporting_document_templates` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/SupportingDocumentTemplateIdentifierNullable" } } }, "VoiceInTrunkGroupIdentifierNullable": { "type": "object", "description": "Identifier of a `voice_in_trunk_groups` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunk_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "VoiceInTrunkGroupToOne": { "type": "object", "description": "Relationship to a `voice_in_trunk_groups` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/VoiceInTrunkGroupIdentifierNullable" } } }, "VoiceInTrunkIdentifier": { "type": "object", "description": "Identifier of a `voice_in_trunks` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunks" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "VoiceInTrunkIdentifierNullable": { "type": "object", "description": "Identifier of a `voice_in_trunks` resource. `null` when nothing is related.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunks" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } }, "nullable": true }, "VoiceInTrunkToMany": { "type": "object", "description": "Relationship to a `voice_in_trunks` resources. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceInTrunkIdentifier" } } } }, "VoiceInTrunkToOne": { "type": "object", "description": "Relationship to a `voice_in_trunks` resource. `data` is present only when the relationship is requested with `include`.", "required": [ "links" ], "properties": { "links": { "$ref": "#/components/schemas/RelationshipLinks" }, "data": { "$ref": "#/components/schemas/VoiceInTrunkIdentifierNullable" } } }, "VoiceOutTrunkIdentifier": { "type": "object", "description": "Identifier of a `voice_out_trunks` resource.", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "voice_out_trunks" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" } } }, "PublicKey": { "type": "object", "description": "An RSA public key for encrypting regulation file uploads. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "public_keys" ] }, "attributes": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "PEM-encoded RSA public key.", "example": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n", "readOnly": true } } } } }, "PublicKeyCollectionDocument": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicKey" } } } }, "Country": { "type": "object", "description": "A country DIDWW has, or may have, coverage in. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "countries" ] }, "attributes": { "type": "object", "required": [ "name", "prefix", "iso" ], "properties": { "name": { "type": "string", "example": "United Kingdom", "readOnly": true }, "prefix": { "type": "string", "nullable": true, "description": "International dialling prefix, without a leading `+`.", "example": "44", "readOnly": true }, "iso": { "type": "string", "description": "ISO 3166-1 alpha-2 code.", "example": "GB", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "regions" ], "properties": { "regions": { "$ref": "#/components/schemas/RegionToMany" } } } } }, "CountryDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Country" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CountryCollectionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Region": { "type": "object", "description": "A region (state, province) of a country. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "regions" ] }, "attributes": { "type": "object", "required": [ "name", "iso" ], "properties": { "name": { "type": "string", "example": "California", "readOnly": true }, "iso": { "type": "string", "nullable": true, "description": "ISO 3166-2 subdivision code, including the country part.", "example": "US-CA", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" } } } } }, "RegionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Region" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "RegionCollectionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "City": { "type": "object", "description": "A city DIDWW has, or may have, coverage in. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "cities" ] }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "London", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "region", "area" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "region": { "$ref": "#/components/schemas/RegionToOne" }, "area": { "$ref": "#/components/schemas/AreaToOne" } } } } }, "CityDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/City" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CityCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/City" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "Area": { "type": "object", "description": "A regulatory area within a country. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "areas" ] }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Greater London", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" } } } } }, "AreaDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Area" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AreaCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Area" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "Pop": { "type": "object", "description": "A DIDWW point of presence. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "pops" ] }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Frankfurt", "readOnly": true } } } } }, "PopCollectionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pop" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidGroupType": { "type": "object", "description": "The kind of number a DID group offers. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "did_group_types" ] }, "attributes": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Local", "readOnly": true } } } } }, "DidGroupTypeDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DidGroupType" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidGroupTypeCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DidGroupType" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "DidGroup": { "type": "object", "description": "A block of numbers sharing a country, city, type and prefix. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "did_groups" ] }, "attributes": { "type": "object", "required": [ "prefix", "area_name", "features", "is_metered", "allow_additional_channels", "service_restrictions" ], "properties": { "prefix": { "type": "string", "description": "Dialling prefix of the group, without the country code — prepend the country's own `prefix` to dial it.", "example": "20", "readOnly": true }, "area_name": { "type": "string", "description": "Human-readable area the group covers.", "example": "London", "readOnly": true }, "features": { "type": "array", "description": "Services the numbers in this group support.", "items": { "type": "string", "enum": [ "voice_in", "voice_out", "t38", "sms_in", "p2p", "a2p", "emergency", "cnam_out" ] }, "readOnly": true }, "is_metered": { "type": "boolean", "description": "True when inbound minutes are billed per minute rather than included.", "readOnly": true }, "allow_additional_channels": { "type": "boolean", "description": "True when extra channels can be bought for a DID from this group.", "readOnly": true }, "service_restrictions": { "type": "string", "nullable": true, "description": "Restrictions that apply to numbers in this group, if any.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "city", "did_group_type", "region", "stock_keeping_units", "address_requirement" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "city": { "$ref": "#/components/schemas/CityToOne" }, "did_group_type": { "$ref": "#/components/schemas/DidGroupTypeToOne" }, "region": { "$ref": "#/components/schemas/RegionToOne" }, "stock_keeping_units": { "$ref": "#/components/schemas/StockKeepingUnitToMany" }, "address_requirement": { "$ref": "#/components/schemas/AddressRequirementToOne" } } }, "meta": { "type": "object", "properties": { "available_dids_enabled": { "type": "boolean", "description": "True when specific numbers from this group can be picked through /available_dids rather than bought in bulk." }, "needs_registration": { "type": "boolean", "description": "True when buying from this group requires a verified address." }, "is_available": { "type": "boolean", "description": "True when numbers are currently in stock." }, "total_count": { "type": "integer", "description": "Numbers currently in stock." } }, "required": [ "available_dids_enabled" ] } } }, "DidGroupDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DidGroup" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidGroupCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DidGroup" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "StockKeepingUnit": { "type": "object", "description": "A priced offer within a DID group — what an order item buys. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "stock_keeping_units" ] }, "attributes": { "type": "object", "required": [ "setup_price", "monthly_price", "channels_included_count" ], "properties": { "setup_price": { "type": "string", "description": "One-off charge, VAT excluded, as a decimal string.", "example": "2.00", "readOnly": true }, "monthly_price": { "type": "string", "description": "Recurring monthly charge, VAT excluded, as a decimal string.", "example": "1.50", "readOnly": true }, "channels_included_count": { "type": "integer", "description": "Simultaneous calls included in the monthly price.", "readOnly": true } } } } }, "NanpaPrefix": { "type": "object", "description": "A NANPA NPA-NXX prefix. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "nanpa_prefixes" ] }, "attributes": { "type": "object", "required": [ "npa", "nxx" ], "properties": { "npa": { "type": "string", "description": "Area code.", "pattern": "^[2-9]\\d\\d$", "example": "212", "readOnly": true }, "nxx": { "type": "string", "description": "Central office code.", "pattern": "^(?!\\d11$)[2-9]\\d{2}$", "example": "555", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "region" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "region": { "$ref": "#/components/schemas/RegionToOne" } } } } }, "NanpaPrefixDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/NanpaPrefix" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "NanpaPrefixCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NanpaPrefix" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "AvailableDid": { "type": "object", "description": "A specific number currently in stock and orderable. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "available_dids" ] }, "attributes": { "type": "object", "required": [ "number" ], "properties": { "number": { "type": "string", "description": "Full number in E.164 without the leading `+`.", "example": "442037691880", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "did_group", "nanpa_prefix" ], "properties": { "did_group": { "$ref": "#/components/schemas/DidGroupToOne" }, "nanpa_prefix": { "$ref": "#/components/schemas/NanpaPrefixToOne" } } } } }, "AvailableDidDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AvailableDid" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/NanpaPrefix" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AvailableDidCollectionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableDid" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/NanpaPrefix" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/AvailableDidCollectionMeta" } } }, "AvailableDidCollectionMeta": { "type": "object", "required": [ "api_version", "total_count" ], "properties": { "api_version": { "type": "string", "description": "V3 API version that served the request.", "example": "2026-04-16" }, "total_count": { "type": "integer", "description": "Numbers matching the filters. The response itself is capped, so this can exceed the size of `data`." } } }, "DidReservation": { "type": "object", "description": "A hold on an available DID. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "did_reservations" ] }, "attributes": { "type": "object", "required": [ "description", "created_at", "expires_at" ], "properties": { "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "description": "When the hold lapses and the number returns to the pool.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "available_did" ], "properties": { "available_did": { "$ref": "#/components/schemas/AvailableDidToOne" } } } } }, "DidReservationDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DidReservation" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/AvailableDid" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/NanpaPrefix" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/DidReservationMeta" } } }, "DidReservationMeta": { "type": "object", "required": [ "api_version", "available_count" ], "properties": { "api_version": { "type": "string", "description": "V3 API version that served the request.", "example": "2026-04-16" }, "available_count": { "type": "integer", "description": "Reservations still available to the customer under its numbers-selection plan." } } }, "DidReservationCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DidReservation" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/AvailableDid" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/NanpaPrefix" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/DidReservationCollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "DidReservationCollectionMeta": { "type": "object", "required": [ "api_version", "total_records", "available_count" ], "properties": { "api_version": { "type": "string", "description": "V3 API version that served the request.", "example": "2026-04-16" }, "total_records": { "type": "integer", "description": "Total number of records matching the request." }, "available_count": { "type": "integer", "description": "Reservations still available to the customer under its numbers-selection plan." } } }, "DidReservationCreatedDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DidReservation" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/AvailableDid" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/NanpaPrefix" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidReservationCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "did_reservations" ] }, "attributes": { "type": "object", "properties": { "description": { "type": "string", "nullable": true, "description": "Free-form customer note." } } }, "relationships": { "type": "object", "properties": { "available_did": { "type": "object", "description": "The number to hold.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AvailableDidIdentifier" } } } }, "required": [ "available_did" ] } } } } }, "Did": { "type": "object", "description": "A DID owned by the customer. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "dids" ] }, "attributes": { "type": "object", "required": [ "number", "description", "blocked", "awaiting_registration", "terminated", "emergency_enabled", "capacity_limit", "channels_included_count", "dedicated_channels_count", "billing_cycles_count", "created_at", "expires_at" ], "properties": { "number": { "type": "string", "description": "Full DID number in E.164 without the leading `+`.", "example": "442037691880", "readOnly": true }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "blocked": { "type": "boolean", "description": "True while the DID cannot receive traffic — blocked by the customer, blocked by DIDWW, or awaiting registration.", "readOnly": true }, "awaiting_registration": { "type": "boolean", "description": "True while the DID is waiting for regulatory registration to complete.", "readOnly": true }, "terminated": { "type": "boolean", "description": "True once the DID has been cancelled. Set it to `true` to cancel the DID, back to `false` to restore it." }, "emergency_enabled": { "type": "boolean", "description": "True when emergency calling is active on the DID.", "readOnly": true }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum number of simultaneous calls. Null means no per-DID limit.", "minimum": 1, "maximum": 32767 }, "channels_included_count": { "type": "integer", "description": "Channels included with the DID by its DID group.", "readOnly": true }, "dedicated_channels_count": { "type": "integer", "description": "Additional channels purchased exclusively for this DID." }, "billing_cycles_count": { "type": "integer", "nullable": true, "description": "Number of billing cycles left before the DID is released. Null means the DID renews indefinitely; `0` means it is pending removal.", "minimum": 0, "maximum": 999 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "End of the current billing period.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "did_group", "order", "capacity_pool", "shared_capacity_group", "address_verification", "voice_in_trunk", "voice_in_trunk_group", "emergency_calling_service", "emergency_verification", "identity" ], "properties": { "did_group": { "$ref": "#/components/schemas/DidGroupToOne" }, "order": { "$ref": "#/components/schemas/OrderToOne" }, "capacity_pool": { "$ref": "#/components/schemas/CapacityPoolToOne" }, "shared_capacity_group": { "$ref": "#/components/schemas/SharedCapacityGroupToOne" }, "address_verification": { "$ref": "#/components/schemas/AddressVerificationToOne" }, "voice_in_trunk": { "$ref": "#/components/schemas/VoiceInTrunkToOne" }, "voice_in_trunk_group": { "$ref": "#/components/schemas/VoiceInTrunkGroupToOne" }, "emergency_calling_service": { "$ref": "#/components/schemas/EmergencyCallingServiceToOne" }, "emergency_verification": { "$ref": "#/components/schemas/EmergencyVerificationToOne" }, "identity": { "$ref": "#/components/schemas/IdentityToOne" } } } } }, "DidDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Did" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Did" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "DidUpdateRequest": { "type": "object", "description": "A DID can be routed to a voice_in_trunk or a voice_in_trunk_group, never both.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "dids" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum number of simultaneous calls. Null means no per-DID limit.", "minimum": 1, "maximum": 32767 }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "terminated": { "type": "boolean", "description": "True once the DID has been cancelled. Set it to `true` to cancel the DID, back to `false` to restore it." }, "billing_cycles_count": { "type": "integer", "nullable": true, "description": "Number of billing cycles left before the DID is released. Null means the DID renews indefinitely; `0` means it is pending removal.", "minimum": 0, "maximum": 999 }, "dedicated_channels_count": { "type": "integer", "description": "Additional channels purchased exclusively for this DID." } } }, "relationships": { "type": "object", "properties": { "capacity_pool": { "type": "object", "description": "Assigns or clears the related resource. Send `data: null` to clear it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CapacityPoolIdentifierNullable" } } }, "shared_capacity_group": { "type": "object", "description": "Assigns or clears the related resource. Send `data: null` to clear it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SharedCapacityGroupIdentifierNullable" } } }, "voice_in_trunk": { "type": "object", "description": "Assigns or clears the related resource. Send `data: null` to clear it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunkIdentifierNullable" } } }, "voice_in_trunk_group": { "type": "object", "description": "Assigns or clears the related resource. Send `data: null` to clear it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunkGroupIdentifierNullable" } } }, "address_verification": { "type": "object", "description": "Send `data: null` to detach it. A DID cannot be attached to one this way.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressVerificationIdentifierNullable" } } }, "emergency_calling_service": { "type": "object", "description": "Send `data: null` to detach it. A DID cannot be attached to one this way.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyCallingServiceIdentifierNullable" } } } } } } } } }, "DidHistory": { "type": "object", "description": "One recorded change to a DID. Retained for the last 90 days. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "did_history" ] }, "attributes": { "type": "object", "required": [ "did_number", "action", "method", "created_at" ], "properties": { "did_number": { "type": "string", "nullable": true, "description": "The number the entry is about, in E.164 without the leading `+`.", "example": "442037691880", "readOnly": true }, "action": { "type": "string", "description": "What happened.", "enum": [ "assigned", "renewed", "canceled", "removed", "billing_cycles_count_changed", "restored" ], "readOnly": true }, "method": { "type": "string", "description": "How it happened — which interface performed the change.", "enum": [ "system", "api2", "api3", "staff", "user_panel", "mcp" ], "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "meta": { "type": "object", "properties": { "from": { "type": "string", "nullable": true, "description": "Previous value." }, "to": { "type": "string", "nullable": true, "description": "New value." } } } } }, "DidHistoryDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/DidHistory" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "DidHistoryCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DidHistory" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "Order": { "type": "object", "description": "An order. Orders have no relationships; their contents live in `items`. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "orders" ] }, "attributes": { "type": "object", "required": [ "reference", "description", "amount", "status", "created_at", "callback_url", "callback_method", "external_reference_id", "items" ], "properties": { "reference": { "type": "string", "description": "Human-readable order reference.", "example": "KTH-650932", "readOnly": true }, "description": { "type": "string", "description": "What was ordered.", "example": "DID", "readOnly": true }, "amount": { "type": "string", "description": "Total charged, VAT included, as a decimal string.", "example": "3.6", "readOnly": true }, "status": { "type": "string", "enum": [ "pending", "completed", "canceled" ], "description": "`pending` while the order is being fulfilled.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the order completes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the order.", "maxLength": 100 }, "items": { "type": "array", "description": "What the order consists of.", "items": { "description": "An ordered item. The shape of `attributes` is determined by `type`.", "anyOf": [ { "$ref": "#/components/schemas/DidOrderItem" }, { "$ref": "#/components/schemas/CapacityOrderItem" }, { "$ref": "#/components/schemas/EmergencyOrderItem" }, { "$ref": "#/components/schemas/GenericOrderItem" } ], "discriminator": { "propertyName": "type", "mapping": { "did_order_items": "#/components/schemas/DidOrderItem", "capacity_order_items": "#/components/schemas/CapacityOrderItem", "emergency_order_items": "#/components/schemas/EmergencyOrderItem", "generic_order_items": "#/components/schemas/GenericOrderItem" } } } } } } } }, "OrderDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "OrderCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "OrderCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "orders" ] }, "attributes": { "type": "object", "properties": { "items": { "type": "array", "minItems": 1, "description": "Items to order. Every item must be of the same `type` — one order buys numbers or channels, never both.", "items": { "description": "An item to order. The accepted `attributes` are determined by `type`.", "anyOf": [ { "$ref": "#/components/schemas/DidOrderItemRequest" }, { "$ref": "#/components/schemas/CapacityOrderItemRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "did_order_items": "#/components/schemas/DidOrderItemRequest", "capacity_order_items": "#/components/schemas/CapacityOrderItemRequest" } } } }, "allow_back_ordering": { "type": "boolean", "default": true, "description": "Place the order even when some numbers are not immediately available. Defaults to true; send false to have the order rejected instead." }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the order completes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed. Send `callback_url` and `callback_method` together: one without the other is rejected.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback. Send `callback_url` and `callback_method` together: one without the other is rejected." }, "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } }, "required": [ "items" ], "anyOf": [ { "required": [ "callback_url", "callback_method" ] }, { "not": { "anyOf": [ { "required": [ "callback_url" ] }, { "required": [ "callback_method" ] } ] } } ] } } } } }, "OrderUpdateRequest": { "type": "object", "description": "Only the external reference of a placed order can be changed.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "orders" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } }, "DidOrderItem": { "type": "object", "description": "Numbers bought from a stock keeping unit.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "did_order_items" ] }, "attributes": { "type": "object", "required": [ "qty", "nrc", "mrc", "prorated_mrc", "billed_from", "billed_to", "did_group_id", "setup_price", "monthly_price" ], "properties": { "qty": { "type": "integer", "description": "Units ordered.", "example": 1 }, "nrc": { "type": "string", "description": "Non-recurring (setup) charge, VAT included, as a decimal string.", "example": "2.1" }, "mrc": { "type": "string", "description": "Monthly recurring charge, VAT included, as a decimal string.", "example": "1.5" }, "prorated_mrc": { "type": "boolean", "description": "True when `mrc` was prorated to the remainder of the billing period." }, "billed_from": { "type": "string", "format": "date", "nullable": true, "description": "Start of the billed period. Null until the item is filled." }, "billed_to": { "type": "string", "format": "date", "nullable": true, "description": "End of the billed period. Null until the item is filled." }, "did_group_id": { "type": "string", "format": "uuid", "nullable": true, "description": "DID group the numbers came from." }, "setup_price": { "type": "string", "deprecated": true, "description": "Deprecated alias of `nrc`, kept for backward compatibility.", "example": "2.1" }, "monthly_price": { "type": "string", "deprecated": true, "description": "Deprecated alias of `mrc`, kept for backward compatibility.", "example": "1.5" } } } } }, "CapacityOrderItem": { "type": "object", "description": "Channels bought for a capacity pool.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "capacity_order_items" ] }, "attributes": { "type": "object", "required": [ "qty", "nrc", "mrc", "prorated_mrc", "billed_from", "billed_to", "capacity_pool_id" ], "properties": { "qty": { "type": "integer", "description": "Units ordered.", "example": 1 }, "nrc": { "type": "string", "description": "Non-recurring (setup) charge, VAT included, as a decimal string.", "example": "2.1" }, "mrc": { "type": "string", "description": "Monthly recurring charge, VAT included, as a decimal string.", "example": "1.5" }, "prorated_mrc": { "type": "boolean", "description": "True when `mrc` was prorated to the remainder of the billing period." }, "billed_from": { "type": "string", "format": "date", "nullable": true, "description": "Start of the billed period. Null until the item is filled." }, "billed_to": { "type": "string", "format": "date", "nullable": true, "description": "End of the billed period. Null until the item is filled." }, "capacity_pool_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Capacity pool the channels were added to." } } } } }, "EmergencyOrderItem": { "type": "object", "description": "Emergency calling activated on a DID.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emergency_order_items" ] }, "attributes": { "type": "object", "required": [ "qty", "nrc", "mrc", "prorated_mrc", "billed_from", "billed_to", "emergency_calling_service_id" ], "properties": { "qty": { "type": "integer", "description": "Units ordered.", "example": 1 }, "nrc": { "type": "string", "description": "Non-recurring (setup) charge, VAT included, as a decimal string.", "example": "2.1" }, "mrc": { "type": "string", "description": "Monthly recurring charge, VAT included, as a decimal string.", "example": "1.5" }, "prorated_mrc": { "type": "boolean", "description": "True when `mrc` was prorated to the remainder of the billing period." }, "billed_from": { "type": "string", "format": "date", "nullable": true, "description": "Start of the billed period. Null until the item is filled." }, "billed_to": { "type": "string", "format": "date", "nullable": true, "description": "End of the billed period. Null until the item is filled." }, "emergency_calling_service_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Emergency calling service the item created." } } } } }, "GenericOrderItem": { "type": "object", "description": "Any other charge — the fallback for order services without a dedicated item type.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "generic_order_items" ] }, "attributes": { "type": "object", "required": [ "qty", "nrc", "mrc", "prorated_mrc", "billed_from", "billed_to" ], "properties": { "qty": { "type": "integer", "description": "Units ordered.", "example": 1 }, "nrc": { "type": "string", "description": "Non-recurring (setup) charge, VAT included, as a decimal string.", "example": "2.1" }, "mrc": { "type": "string", "description": "Monthly recurring charge, VAT included, as a decimal string.", "example": "1.5" }, "prorated_mrc": { "type": "boolean", "description": "True when `mrc` was prorated to the remainder of the billing period." }, "billed_from": { "type": "string", "format": "date", "nullable": true, "description": "Start of the billed period. Null until the item is filled." }, "billed_to": { "type": "string", "format": "date", "nullable": true, "description": "End of the billed period. Null until the item is filled." } } } } }, "DidOrderItemRequest": { "type": "object", "description": "Buy numbers from a stock keeping unit. At most one of `qty`, `did_reservation_id` and `available_did_id` may be sent: more than one is rejected, and sending none of them buys one number.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "did_order_items" ] }, "attributes": { "type": "object", "required": [ "sku_id" ], "properties": { "sku_id": { "type": "string", "format": "uuid", "description": "Stock keeping unit to buy from." }, "qty": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "How many numbers to buy from the SKU." }, "did_reservation_id": { "type": "string", "format": "uuid", "description": "Buy the number held by this reservation." }, "available_did_id": { "type": "string", "format": "uuid", "description": "Buy this specific available number." }, "nanpa_prefix_id": { "type": "string", "format": "uuid", "description": "Restrict the numbers to this NANPA prefix." }, "billing_cycles_count": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Billing cycles to keep the numbers for before releasing them. Omit to renew indefinitely." } } } } }, "CapacityOrderItemRequest": { "type": "object", "description": "Buy channels for a capacity pool. `qty` defaults to one channel, and the pool's own minimum order applies.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "capacity_order_items" ] }, "attributes": { "type": "object", "required": [ "capacity_pool_id" ], "properties": { "qty": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "How many channels to buy." }, "capacity_pool_id": { "type": "string", "format": "uuid", "description": "Capacity pool to add the channels to." } } } } }, "Balance": { "type": "object", "description": "The authenticated customer's balance. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "balances" ] }, "attributes": { "type": "object", "required": [ "balance", "credit", "total_balance" ], "properties": { "balance": { "type": "string", "description": "Prepaid funds available, as a decimal string with two places.", "example": "1000.00", "readOnly": true }, "credit": { "type": "string", "description": "Credit extended on top of the prepaid funds, as a decimal string.", "example": "0.00", "readOnly": true }, "total_balance": { "type": "string", "description": "Spendable total — `balance` plus `credit`.", "example": "1000.00", "readOnly": true } } } } }, "BalanceDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Balance" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Export": { "type": "object", "description": "An asynchronous CDR export. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "exports" ] }, "attributes": { "type": "object", "required": [ "export_type", "status", "url", "filters", "callback_url", "callback_method", "external_reference_id", "created_at" ], "properties": { "export_type": { "type": "string", "description": "`cdr_in` exports inbound call records, `cdr_out` outbound ones.", "enum": [ "cdr_in", "cdr_out" ] }, "status": { "type": "string", "description": "Becomes `completed` once the file is ready to download.", "enum": [ "pending", "completed", "processing" ], "readOnly": true }, "url": { "type": "string", "nullable": true, "description": "Download URL of the generated file. Null until the export completes.", "readOnly": true }, "filters": { "type": "object", "description": "The criteria the export was created with. An export created at an earlier API version carries that version's keys.", "properties": { "year": { "type": "string", "description": "Year of the exported period. Earlier versions only." }, "month": { "type": "string", "description": "Month of the exported period. Earlier versions only." }, "did_number": { "type": "string", "description": "Restricts the export to one number, in E.164 without the leading `+`." }, "from": { "type": "string", "description": "Start of the exported period, as `YYYY-MM-DD HH:MM:SS` in UTC.", "example": "2026-04-01 00:00:00" }, "to": { "type": "string", "description": "End of the exported period, as `YYYY-MM-DD HH:MM:SS` in UTC.", "example": "2026-04-30 23:59:59" }, "day": { "type": "string", "description": "Day of the exported period. Earlier versions only." }, "voice_out_trunk.id": { "type": "string", "format": "uuid", "description": "Restricts the export to one outbound trunk." } } }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the export completes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the export.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true } } } } }, "ExportDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Export" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ExportCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "ExportCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "exports" ] }, "attributes": { "type": "object", "properties": { "export_type": { "type": "string", "description": "`cdr_in` exports inbound call records, `cdr_out` outbound ones.", "enum": [ "cdr_in", "cdr_out" ] }, "filters": { "type": "object", "required": [ "from", "to" ], "additionalProperties": false, "description": "Selection criteria for the exported records. `from` and `to` are required for both export types and must fall within the current or the two preceding months, with `from` before `to` and neither in the future. A `cdr_in` export also accepts `did_number`. A `cdr_out` export also accepts `voice_out_trunk.id`. Any other key is rejected.", "properties": { "from": { "type": "string", "description": "Start of the exported period, as `YYYY-MM-DD HH:MM:SS` in UTC.", "example": "2026-04-01 00:00:00" }, "to": { "type": "string", "description": "End of the exported period, as `YYYY-MM-DD HH:MM:SS` in UTC.", "example": "2026-04-30 23:59:59" }, "did_number": { "type": "string", "description": "Restricts the export to one number, in E.164 without the leading `+`." }, "voice_out_trunk.id": { "type": "string", "format": "uuid", "description": "Restricts the export to one outbound trunk." } } }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the export completes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed. Send `callback_url` and `callback_method` together: one without the other is rejected.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback. Send `callback_url` and `callback_method` together: one without the other is rejected." }, "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } }, "required": [ "export_type", "filters" ], "anyOf": [ { "required": [ "callback_url", "callback_method" ] }, { "not": { "anyOf": [ { "required": [ "callback_url" ] }, { "required": [ "callback_method" ] } ] } } ] } } } } }, "ExportUpdateRequest": { "type": "object", "description": "Only the external reference of an export can be changed.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "exports" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } }, "CapacityPool": { "type": "object", "description": "A pool of channels the customer has bought, shared across DIDs. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "capacity_pools" ] }, "attributes": { "type": "object", "required": [ "name", "renew_date", "total_channels_count", "assigned_channels_count", "minimum_limit", "minimum_qty_per_order", "setup_price", "monthly_price", "metered_rate" ], "properties": { "name": { "type": "string", "description": "Name of the pool template.", "example": "Europe", "readOnly": true }, "renew_date": { "type": "string", "format": "date", "description": "Next renewal date.", "readOnly": true }, "total_channels_count": { "type": "integer", "description": "Channels owned." }, "assigned_channels_count": { "type": "integer", "description": "Channels currently assigned to DIDs.", "readOnly": true }, "minimum_limit": { "type": "integer", "description": "Fewest channels the pool can be shrunk to.", "readOnly": true }, "minimum_qty_per_order": { "type": "integer", "description": "Fewest channels a single capacity order must buy.", "readOnly": true }, "setup_price": { "type": "string", "description": "One-off charge per channel, as a decimal string.", "example": "1.00", "readOnly": true }, "monthly_price": { "type": "string", "description": "Recurring monthly charge per channel, as a decimal string.", "example": "5.00", "readOnly": true }, "metered_rate": { "type": "string", "description": "Per-minute rate applied once the pool is exhausted, as a decimal string.", "example": "0.0100", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "countries", "shared_capacity_groups", "qty_based_pricings" ], "properties": { "countries": { "$ref": "#/components/schemas/CountryToMany" }, "shared_capacity_groups": { "$ref": "#/components/schemas/SharedCapacityGroupToMany" }, "qty_based_pricings": { "$ref": "#/components/schemas/QtyBasedPricingToMany" } } } } }, "CapacityPoolDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/CapacityPool" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CapacityPoolCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityPool" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "CapacityPoolUpdateRequest": { "type": "object", "description": "Releases channels from the pool. Channels are bought through POST /orders.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "capacity_pools" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "total_channels_count": { "type": "integer", "description": "New channel count. Must be lower than the current one and not below `assigned_channels_count` or `minimum_limit`; buy more channels with an order." } } } } } } }, "QtyBasedPricing": { "type": "object", "description": "A volume price break of a capacity pool. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "qty_based_pricings" ] }, "attributes": { "type": "object", "required": [ "qty", "setup_price", "monthly_price" ], "properties": { "qty": { "type": "integer", "description": "Channel count this break applies from.", "readOnly": true }, "setup_price": { "type": "string", "description": "One-off charge per channel at this volume, as a decimal string.", "example": "1.00", "readOnly": true }, "monthly_price": { "type": "string", "description": "Recurring monthly charge per channel at this volume, as a decimal string.", "example": "4.50", "readOnly": true } } } } }, "SharedCapacityGroup": { "type": "object", "description": "A set of DIDs sharing channels drawn from a capacity pool. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "shared_capacity_groups" ] }, "attributes": { "type": "object", "required": [ "name", "shared_channels_count", "metered_channels_count", "external_reference_id", "created_at" ], "properties": { "name": { "type": "string", "example": "London office" }, "shared_channels_count": { "type": "integer", "description": "Channels drawn from the pool for this group." }, "metered_channels_count": { "type": "integer", "description": "Extra channels billed per minute once the shared ones are busy. Zero means no metered overflow — `overload_capacity` is NOT NULL with a default of 0." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "capacity_pool", "dids" ], "properties": { "capacity_pool": { "$ref": "#/components/schemas/CapacityPoolToOne" }, "dids": { "$ref": "#/components/schemas/DidToMany" } } } } }, "SharedCapacityGroupDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SharedCapacityGroup" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SharedCapacityGroupCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SharedCapacityGroup" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "SharedCapacityGroupCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "shared_capacity_groups" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "London office" }, "shared_channels_count": { "type": "integer", "description": "Channels drawn from the pool for this group." }, "metered_channels_count": { "type": "integer", "description": "Extra channels billed per minute once the shared ones are busy. Zero means no metered overflow — `overload_capacity` is NOT NULL with a default of 0." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 } }, "required": [ "name" ] }, "relationships": { "type": "object", "properties": { "capacity_pool": { "type": "object", "description": "Pool the channels come from.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CapacityPoolIdentifier" } } }, "dids": { "type": "object", "description": "Replaces the whole set of DIDs sharing these channels.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } } }, "required": [ "capacity_pool" ] } } } } }, "SharedCapacityGroupUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "shared_capacity_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "London office" }, "shared_channels_count": { "type": "integer", "description": "Channels drawn from the pool for this group." }, "metered_channels_count": { "type": "integer", "description": "Extra channels billed per minute once the shared ones are busy. Zero means no metered overflow — `overload_capacity` is NOT NULL with a default of 0." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 } } }, "relationships": { "type": "object", "properties": { "capacity_pool": { "type": "object", "description": "Pool the channels come from.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CapacityPoolIdentifier" } } }, "dids": { "type": "object", "description": "Replaces the whole set of DIDs sharing these channels.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } } } } } } } }, "VoiceInTrunk": { "type": "object", "description": "An inbound voice trunk a DID can be routed to. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "voice_in_trunks" ] }, "attributes": { "type": "object", "required": [ "name", "description", "external_reference_id", "priority", "weight", "capacity_limit", "cli_format", "cli_prefix", "ringing_timeout", "created_at", "configuration" ], "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "Primary SIP" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "priority": { "type": "integer", "description": "Routing priority within a trunk group; lower wins.", "minimum": 0, "maximum": 65535 }, "weight": { "type": "integer", "description": "Load-balancing weight among equal-priority trunks in a trunk group.", "minimum": 0, "maximum": 65535 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls on the trunk. Null means no limit.", "minimum": 1, "maximum": 32767 }, "cli_format": { "type": "string", "nullable": true, "description": "Format the caller ID is delivered in. A blank value is stored as `e164`.", "enum": [ "e164", "local", "raw", null ], "example": "e164" }, "cli_prefix": { "type": "string", "nullable": true, "description": "Prefix prepended to the caller ID. Letters, digits, `+` and `#` only.", "maxLength": 7 }, "ringing_timeout": { "type": "integer", "nullable": true, "description": "Seconds to ring before giving up. Null uses the platform default.", "minimum": 1, "maximum": 32 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "configuration": { "description": "Transport configuration. `attributes` is determined by `type`: a SIP trunk delivers calls to a SIP host, a PSTN trunk forwards them to a phone number.", "anyOf": [ { "$ref": "#/components/schemas/SipConfiguration" }, { "$ref": "#/components/schemas/PstnConfiguration" } ], "discriminator": { "propertyName": "type", "mapping": { "sip_configurations": "#/components/schemas/SipConfiguration", "pstn_configurations": "#/components/schemas/PstnConfiguration" } } } } }, "relationships": { "type": "object", "required": [ "voice_in_trunk_group", "pop" ], "properties": { "voice_in_trunk_group": { "$ref": "#/components/schemas/VoiceInTrunkGroupToOne" }, "pop": { "$ref": "#/components/schemas/PopToOne" } } } } }, "VoiceInTrunkDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunk" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "VoiceInTrunkCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceInTrunk" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "VoiceInTrunkCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunks" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "Primary SIP" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "priority": { "type": "integer", "description": "Routing priority within a trunk group; lower wins.", "minimum": 0, "maximum": 65535 }, "weight": { "type": "integer", "description": "Load-balancing weight among equal-priority trunks in a trunk group.", "minimum": 0, "maximum": 65535 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls on the trunk. Null means no limit.", "minimum": 1, "maximum": 32767 }, "cli_format": { "type": "string", "nullable": true, "description": "Format the caller ID is delivered in. A blank value is stored as `e164`.", "enum": [ "e164", "local", "raw", null ], "example": "e164" }, "cli_prefix": { "type": "string", "nullable": true, "description": "Prefix prepended to the caller ID. Letters, digits, `+` and `#` only.", "maxLength": 7 }, "ringing_timeout": { "type": "integer", "nullable": true, "description": "Seconds to ring before giving up. Null uses the platform default.", "minimum": 1, "maximum": 32 }, "configuration": { "description": "Transport configuration. `attributes` is determined by `type`: a SIP trunk delivers calls to a SIP host, a PSTN trunk forwards them to a phone number.", "anyOf": [ { "$ref": "#/components/schemas/SipConfigurationRequest" }, { "$ref": "#/components/schemas/PstnConfigurationRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "sip_configurations": "#/components/schemas/SipConfigurationRequest", "pstn_configurations": "#/components/schemas/PstnConfigurationRequest" } } } }, "required": [ "name", "configuration" ] }, "relationships": { "type": "object", "properties": { "voice_in_trunk_group": { "type": "object", "description": "Trunk group to join.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunkGroupIdentifierNullable" } } }, "pop": { "type": "object", "description": "Point of presence to pin the trunk to.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PopIdentifierNullable" } } } } } } } } }, "VoiceInTrunkUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunks" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "Primary SIP" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "priority": { "type": "integer", "description": "Routing priority within a trunk group; lower wins.", "minimum": 0, "maximum": 65535 }, "weight": { "type": "integer", "description": "Load-balancing weight among equal-priority trunks in a trunk group.", "minimum": 0, "maximum": 65535 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls on the trunk. Null means no limit.", "minimum": 1, "maximum": 32767 }, "cli_format": { "type": "string", "nullable": true, "description": "Format the caller ID is delivered in. A blank value is stored as `e164`.", "enum": [ "e164", "local", "raw", null ], "example": "e164" }, "cli_prefix": { "type": "string", "nullable": true, "description": "Prefix prepended to the caller ID. Letters, digits, `+` and `#` only.", "maxLength": 7 }, "ringing_timeout": { "type": "integer", "nullable": true, "description": "Seconds to ring before giving up. Null uses the platform default.", "minimum": 1, "maximum": 32 }, "configuration": { "description": "Transport configuration. `attributes` is determined by `type`: a SIP trunk delivers calls to a SIP host, a PSTN trunk forwards them to a phone number. `type` must match the trunk's; the members you send are written and the rest keep their stored values.", "anyOf": [ { "$ref": "#/components/schemas/SipConfigurationRequest" }, { "$ref": "#/components/schemas/PstnConfigurationRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "sip_configurations": "#/components/schemas/SipConfigurationRequest", "pstn_configurations": "#/components/schemas/PstnConfigurationRequest" } } } } }, "relationships": { "type": "object", "properties": { "voice_in_trunk_group": { "type": "object", "description": "Trunk group to join, or `null` to leave.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunkGroupIdentifierNullable" } } }, "pop": { "type": "object", "description": "Point of presence to pin the trunk to, or `null`.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PopIdentifierNullable" } } } } } } } } }, "SipConfiguration": { "type": "object", "description": "Delivery over SIP.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "sip_configurations" ] }, "attributes": { "type": "object", "properties": { "host": { "type": "string", "nullable": true, "description": "Hostname or IP calls are sent to. Required while `enabled_sip_registration` is false, and rejected while it is true — a registering trunk has no fixed host.", "example": "sip.example.com" }, "port": { "type": "integer", "nullable": true, "description": "SIP port. Must be blank when `enabled_sip_registration` is true.", "minimum": 1, "maximum": 65535 }, "username": { "type": "string", "nullable": true, "description": "User part of the request URI. No whitespace and no `@`.", "pattern": "^[^\\s@]*$" }, "transport_protocol_id": { "type": "integer", "description": "SIP transport: 1 UDP, 2 TCP, 3 TLS.", "enum": [ 1, 2, 3 ] }, "network_protocol_priority": { "type": "string", "description": "IP version preference when resolving the host.", "enum": [ "force_ipv4", "force_ipv6", "any", "prefer_ipv4", "prefer_ipv6" ] }, "resolve_ruri": { "type": "boolean", "description": "Resolve the request URI host before sending." }, "use_did_in_ruri": { "type": "boolean", "description": "Put the DID number in the request URI user part. Requires SIP registration." }, "codec_ids": { "type": "array", "description": "Offered codecs, in preference order, as platform codec ids: 6 (telephone-event), 7 (G723), 8 (G729), 9 (PCMU), 10 (PCMA), 12 (speex), 13 (GSM), 14 (G726-32), 15 (G721), 16 (G726-24), 17 (G726-40), 18 (G726-16), 19 (L16). Required.", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "enum": [ 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18, 19 ] } }, "rx_dtmf_format_id": { "type": "integer", "description": "Inbound DTMF format: 1 RFC 2833, 2 SIP INFO application/dtmf-relay OR application/dtmf, 3 RFC 2833 OR SIP INFO.", "enum": [ 1, 2, 3 ] }, "tx_dtmf_format_id": { "type": "integer", "description": "Outbound DTMF format: 0 Disable sending, 1 RFC 2833, 2 SIP INFO application/dtmf-relay, 4 SIP INFO application/dtmf.", "enum": [ 0, 1, 2, 4 ] }, "auth_enabled": { "type": "boolean", "description": "Authenticate outbound requests to the host." }, "auth_user": { "type": "string", "nullable": true, "description": "Digest user for outbound authentication. Required while `auth_enabled` is true, and rejected while it is false." }, "auth_password": { "type": "string", "nullable": true, "description": "Digest password. Required while `auth_enabled` is true, and rejected while it is false." }, "auth_from_user": { "type": "string", "nullable": true, "description": "From-header user for authentication." }, "auth_from_domain": { "type": "string", "nullable": true, "description": "From-header domain for authentication." }, "enabled_sip_registration": { "type": "boolean", "description": "Let the trunk register with DIDWW instead of receiving calls at a fixed host. Enabling it generates `incoming_auth_username` / `incoming_auth_password`." }, "incoming_auth_username": { "type": "string", "nullable": true, "description": "Generated SIP registration username. Read-only — sending it is rejected.", "readOnly": true }, "incoming_auth_password": { "type": "string", "nullable": true, "description": "Generated SIP registration password. Read-only — sending it is rejected.", "readOnly": true }, "sst_enabled": { "type": "boolean", "description": "Enable SIP session timers." }, "sst_min_timer": { "type": "integer", "nullable": true, "description": "Shortest session interval accepted. Required while `sst_enabled` is true.", "minimum": 1 }, "sst_max_timer": { "type": "integer", "nullable": true, "description": "Longest session interval accepted. Required while `sst_enabled` is true, and never below `sst_min_timer`." }, "sst_session_expires": { "type": "integer", "nullable": true, "description": "Session interval offered, between `sst_min_timer` and `sst_max_timer`." }, "sst_refresh_method_id": { "type": "integer", "description": "Session refresh method: 1 Invite, 2 Update, 3 Update fallback Invite.", "enum": [ 1, 2, 3 ] }, "sst_accept_501": { "type": "boolean", "description": "Treat a 501 to a session refresh as success." }, "sip_timer_b": { "type": "integer", "description": "INVITE transaction timeout, ms.", "minimum": 1000, "maximum": 64000 }, "dns_srv_failover_timer": { "type": "integer", "nullable": true, "description": "SRV failover timeout, ms. Never above `sip_timer_b`.", "minimum": 1 }, "rtp_ping": { "type": "boolean", "nullable": true, "description": "Send RTP keep-alives." }, "rtp_timeout": { "type": "integer", "description": "Drop the call after this many seconds of RTP silence.", "minimum": 5, "maximum": 600 }, "force_symmetric_rtp": { "type": "boolean", "nullable": true, "description": "Learn the remote RTP address from arriving packets." }, "symmetric_rtp_ignore_rtcp": { "type": "boolean", "nullable": true }, "allowed_rtp_ips": { "type": "array", "nullable": true, "description": "Restrict RTP to these addresses. Null means no restriction.", "maxItems": 10, "uniqueItems": true, "items": { "type": "string" } }, "media_encryption_mode": { "type": "string", "description": "Media encryption offered to the trunk.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "stir_shaken_mode": { "type": "string", "description": "How STIR/SHAKEN attestation is passed on.", "enum": [ "disabled", "original", "pai", "original_pai", "verstat" ] }, "diversion_relay_policy": { "type": "string", "description": "How an incoming Diversion header is relayed.", "enum": [ "none", "as_is", "sip", "tel" ] }, "diversion_inject_mode": { "type": "string", "description": "Whether DIDWW adds a Diversion header of its own.", "enum": [ "none", "did_number" ] }, "cnam_lookup": { "type": "boolean", "description": "Look the caller name up and deliver it." }, "max_transfers": { "type": "integer", "description": "Maximum SIP REFER transfers allowed.", "minimum": 0, "maximum": 8 }, "max_30x_redirects": { "type": "integer", "description": "Maximum 3xx redirects followed.", "minimum": 0, "maximum": 8 }, "rerouting_disconnect_code_ids": { "type": "array", "nullable": true, "description": "Disconnect codes that trigger rerouting to the next trunk, as platform ids rather than SIP status codes.", "uniqueItems": true, "items": { "type": "integer", "enum": [ 56, 57, 58, 59, 60, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 86, 87, 88, 89, 90, 91, 92, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 1505 ] } } }, "required": [ "host", "port", "username", "transport_protocol_id", "network_protocol_priority", "resolve_ruri", "use_did_in_ruri", "codec_ids", "rx_dtmf_format_id", "tx_dtmf_format_id", "auth_enabled", "auth_user", "auth_password", "auth_from_user", "auth_from_domain", "enabled_sip_registration", "incoming_auth_username", "incoming_auth_password", "sst_enabled", "sst_min_timer", "sst_max_timer", "sst_session_expires", "sst_refresh_method_id", "sst_accept_501", "sip_timer_b", "dns_srv_failover_timer", "rtp_ping", "rtp_timeout", "force_symmetric_rtp", "symmetric_rtp_ignore_rtcp", "allowed_rtp_ips", "media_encryption_mode", "stir_shaken_mode", "diversion_relay_policy", "diversion_inject_mode", "cnam_lookup", "max_transfers", "max_30x_redirects", "rerouting_disconnect_code_ids" ] } } }, "PstnConfiguration": { "type": "object", "description": "Delivery by forwarding to a phone number.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "pstn_configurations" ] }, "attributes": { "type": "object", "properties": { "dst": { "type": "string", "description": "Number calls are forwarded to, in E.164 without the leading `+`. Digits only, and always required.", "maxLength": 15, "example": "442037691880" } }, "required": [ "dst" ] } } }, "SipConfigurationRequest": { "type": "object", "description": "Delivery over SIP.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "sip_configurations" ] }, "attributes": { "type": "object", "properties": { "username": { "type": "string", "nullable": true, "description": "User part of the request URI. No whitespace and no `@`.", "pattern": "^[^\\s@]*$" }, "host": { "type": "string", "nullable": true, "description": "Hostname or IP calls are sent to. Required while `enabled_sip_registration` is false, and rejected while it is true — a registering trunk has no fixed host.", "example": "sip.example.com" }, "port": { "type": "integer", "nullable": true, "description": "SIP port. Must be blank when `enabled_sip_registration` is true.", "minimum": 1, "maximum": 65535 }, "codec_ids": { "type": "array", "description": "Offered codecs, in preference order, as platform codec ids: 6 (telephone-event), 7 (G723), 8 (G729), 9 (PCMU), 10 (PCMA), 12 (speex), 13 (GSM), 14 (G726-32), 15 (G721), 16 (G726-24), 17 (G726-40), 18 (G726-16), 19 (L16). Required.", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "enum": [ 6, 7, 8, 9, 10, 12, 13, 14, 15, 16, 17, 18, 19 ] } }, "rx_dtmf_format_id": { "type": "integer", "description": "Inbound DTMF format: 1 RFC 2833, 2 SIP INFO application/dtmf-relay OR application/dtmf, 3 RFC 2833 OR SIP INFO.", "enum": [ 1, 2, 3 ] }, "tx_dtmf_format_id": { "type": "integer", "description": "Outbound DTMF format: 0 Disable sending, 1 RFC 2833, 2 SIP INFO application/dtmf-relay, 4 SIP INFO application/dtmf.", "enum": [ 0, 1, 2, 4 ] }, "resolve_ruri": { "type": "boolean", "description": "Resolve the request URI host before sending." }, "auth_enabled": { "type": "boolean", "description": "Authenticate outbound requests to the host." }, "auth_user": { "type": "string", "nullable": true, "description": "Digest user for outbound authentication. Required while `auth_enabled` is true, and rejected while it is false." }, "auth_password": { "type": "string", "nullable": true, "description": "Digest password. Required while `auth_enabled` is true, and rejected while it is false." }, "auth_from_user": { "type": "string", "nullable": true, "description": "From-header user for authentication." }, "auth_from_domain": { "type": "string", "nullable": true, "description": "From-header domain for authentication." }, "sst_enabled": { "type": "boolean", "description": "Enable SIP session timers." }, "sst_min_timer": { "type": "integer", "nullable": true, "description": "Shortest session interval accepted. Required while `sst_enabled` is true.", "minimum": 1 }, "sst_max_timer": { "type": "integer", "nullable": true, "description": "Longest session interval accepted. Required while `sst_enabled` is true, and never below `sst_min_timer`." }, "sst_accept_501": { "type": "boolean", "description": "Treat a 501 to a session refresh as success." }, "sip_timer_b": { "type": "integer", "description": "INVITE transaction timeout, ms.", "minimum": 1000, "maximum": 64000 }, "dns_srv_failover_timer": { "type": "integer", "nullable": true, "description": "SRV failover timeout, ms. Never above `sip_timer_b`.", "minimum": 1 }, "rtp_ping": { "type": "boolean", "nullable": true, "description": "Send RTP keep-alives." }, "rtp_timeout": { "type": "integer", "description": "Drop the call after this many seconds of RTP silence.", "minimum": 5, "maximum": 600 }, "force_symmetric_rtp": { "type": "boolean", "nullable": true, "description": "Learn the remote RTP address from arriving packets." }, "symmetric_rtp_ignore_rtcp": { "type": "boolean", "nullable": true }, "rerouting_disconnect_code_ids": { "type": "array", "nullable": true, "description": "Disconnect codes that trigger rerouting to the next trunk, as platform ids rather than SIP status codes.", "uniqueItems": true, "items": { "type": "integer", "enum": [ 56, 57, 58, 59, 60, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 86, 87, 88, 89, 90, 91, 92, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 1505 ] } }, "sst_session_expires": { "type": "integer", "nullable": true, "description": "Session interval offered, between `sst_min_timer` and `sst_max_timer`." }, "sst_refresh_method_id": { "type": "integer", "description": "Session refresh method: 1 Invite, 2 Update, 3 Update fallback Invite.", "enum": [ 1, 2, 3 ] }, "transport_protocol_id": { "type": "integer", "description": "SIP transport: 1 UDP, 2 TCP, 3 TLS.", "enum": [ 1, 2, 3 ] }, "max_transfers": { "type": "integer", "description": "Maximum SIP REFER transfers allowed.", "minimum": 0, "maximum": 8 }, "max_30x_redirects": { "type": "integer", "description": "Maximum 3xx redirects followed.", "minimum": 0, "maximum": 8 }, "media_encryption_mode": { "type": "string", "description": "Media encryption offered to the trunk.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "stir_shaken_mode": { "type": "string", "description": "How STIR/SHAKEN attestation is passed on.", "enum": [ "disabled", "original", "pai", "original_pai", "verstat" ] }, "allowed_rtp_ips": { "type": "array", "nullable": true, "description": "Restrict RTP to these addresses. Null means no restriction.", "maxItems": 10, "uniqueItems": true, "items": { "type": "string" } }, "network_protocol_priority": { "type": "string", "description": "IP version preference when resolving the host.", "enum": [ "force_ipv4", "force_ipv6", "any", "prefer_ipv4", "prefer_ipv6" ] }, "enabled_sip_registration": { "type": "boolean", "description": "Let the trunk register with DIDWW instead of receiving calls at a fixed host. Enabling it generates `incoming_auth_username` / `incoming_auth_password`." }, "use_did_in_ruri": { "type": "boolean", "description": "Put the DID number in the request URI user part. Requires SIP registration." }, "diversion_relay_policy": { "type": "string", "description": "How an incoming Diversion header is relayed.", "enum": [ "none", "as_is", "sip", "tel" ] }, "diversion_inject_mode": { "type": "string", "description": "Whether DIDWW adds a Diversion header of its own.", "enum": [ "none", "did_number" ] }, "cnam_lookup": { "type": "boolean", "description": "Look the caller name up and deliver it." } } } } }, "PstnConfigurationRequest": { "type": "object", "description": "Delivery by forwarding to a phone number.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "pstn_configurations" ] }, "attributes": { "type": "object", "properties": { "dst": { "type": "string", "description": "Number calls are forwarded to, in E.164 without the leading `+`. Digits only, and always required.", "maxLength": 15, "example": "442037691880" } } } } }, "VoiceInTrunkGroup": { "type": "object", "description": "A group of inbound voice trunks, routed to as a unit. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "voice_in_trunk_groups" ] }, "attributes": { "type": "object", "required": [ "name", "capacity_limit", "external_reference_id", "created_at" ], "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "EU inbound" }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls across the whole group. Null means no limit.", "minimum": 1, "maximum": 32767 }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "voice_in_trunks" ], "properties": { "voice_in_trunks": { "$ref": "#/components/schemas/VoiceInTrunkToMany" } } }, "meta": { "type": "object", "properties": { "trunks_count": { "type": "integer", "description": "Trunks currently in the group." } }, "required": [ "trunks_count" ] } } }, "VoiceInTrunkGroupDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceInTrunkGroup" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "VoiceInTrunkGroupCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceInTrunkGroup" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "VoiceInTrunkGroupCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunk_groups" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "EU inbound" }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls across the whole group. Null means no limit.", "minimum": 1, "maximum": 32767 }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 } }, "required": [ "name" ] }, "relationships": { "type": "object", "properties": { "voice_in_trunks": { "type": "object", "description": "Replaces the whole membership of the group with the trunks listed here. At most 10 distinct trunks; a trunk listed twice is counted once.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceInTrunkIdentifier" } } } } } } } } } }, "VoiceInTrunkGroupUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_in_trunk_groups" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique among the trunks and trunk groups of the account — they share one name space.", "example": "EU inbound" }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous calls across the whole group. Null means no limit.", "minimum": 1, "maximum": 32767 }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the group.", "maxLength": 100 } } }, "relationships": { "type": "object", "properties": { "voice_in_trunks": { "type": "object", "description": "Replaces the whole membership of the group with the trunks listed here. At most 10 distinct trunks; a trunk listed twice is counted once.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceInTrunkIdentifier" } } } } } } } } } }, "VoiceOutTrunk": { "type": "object", "description": "An outbound voice trunk: where DIDWW accepts calls from and how it authenticates them. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "voice_out_trunks" ] }, "attributes": { "type": "object", "required": [ "name", "status", "external_reference_id", "capacity_limit", "allow_any_did_as_cli", "on_cli_mismatch_action", "default_dst_action", "dst_prefixes", "media_encryption_mode", "allowed_rtp_ips", "force_symmetric_rtp", "rtp_ping", "rtp_timeout", "threshold_amount", "callback_url", "emergency_enable_all", "created_at", "threshold_reached", "authentication_method" ], "properties": { "name": { "type": "string", "example": "Outbound EU" }, "status": { "type": "string", "description": "Set to `blocked` to stop the trunk from placing calls.", "enum": [ "active", "blocked" ] }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous outbound calls. Null means no limit.", "minimum": 1, "maximum": 32767 }, "allow_any_did_as_cli": { "type": "boolean", "description": "Allow any DID the customer owns as the caller ID. While true the `dids` relationship is managed automatically and cannot be assigned." }, "on_cli_mismatch_action": { "type": "string", "description": "What to do when the caller ID is not one of the allowed DIDs.", "enum": [ "reject_call", "replace_cli", "send_original_cli", "randomize_cli" ] }, "default_dst_action": { "type": "string", "description": "Whether destinations not listed in `dst_prefixes` are allowed.", "enum": [ "allow_all", "reject_all" ] }, "dst_prefixes": { "type": "array", "description": "Destination prefixes the `default_dst_action` is inverted for, as digits without a leading `+` or any separator. Repeated prefixes are accepted and stored once.", "items": { "type": "string", "example": "4420" } }, "media_encryption_mode": { "type": "string", "description": "Media encryption required of the trunk.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "allowed_rtp_ips": { "type": "array", "nullable": true, "description": "Restrict RTP to these addresses. Null means no restriction.", "maxItems": 60, "uniqueItems": true, "items": { "type": "string" } }, "force_symmetric_rtp": { "type": "boolean", "description": "Learn the remote RTP address from arriving packets." }, "rtp_ping": { "type": "boolean", "description": "Send RTP keep-alives." }, "rtp_timeout": { "type": "integer", "description": "Drop the call after this many seconds of RTP silence.", "minimum": 30, "maximum": 600 }, "threshold_amount": { "type": "string", "description": "Spending on the trunk that triggers a notification, as a decimal string. The accepted range depends on the account.", "example": "100.00" }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the spending threshold is reached. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "emergency_enable_all": { "type": "boolean", "description": "Allow emergency calls from any DID the customer owns. While true the `emergency_dids` relationship cannot be assigned." }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "threshold_reached": { "type": "boolean", "description": "True once spending on the trunk has passed `threshold_amount`.", "readOnly": true }, "authentication_method": { "description": "How DIDWW authenticates calls from the trunk. `attributes` is determined by `type`: `credentials_and_ip` returns the generated `username` / `password` alongside the allowed addresses, `ip_only` authenticates by address alone, and `twilio` trusts a Twilio account SID.", "anyOf": [ { "$ref": "#/components/schemas/CredentialsAndIpAuthentication" }, { "$ref": "#/components/schemas/IpOnlyAuthentication" }, { "$ref": "#/components/schemas/TwilioAuthentication" } ], "discriminator": { "propertyName": "type", "mapping": { "credentials_and_ip": "#/components/schemas/CredentialsAndIpAuthentication", "ip_only": "#/components/schemas/IpOnlyAuthentication", "twilio": "#/components/schemas/TwilioAuthentication" } } } } }, "relationships": { "type": "object", "required": [ "dids", "emergency_dids" ], "properties": { "dids": { "$ref": "#/components/schemas/DidToMany" }, "emergency_dids": { "$ref": "#/components/schemas/DidToMany" } } }, "meta": { "type": "object", "properties": { "spent_amount": { "type": "string", "description": "Spent on this trunk in the current billing period, as a decimal string.", "example": "12.34" } }, "required": [ "spent_amount" ] } } }, "VoiceOutTrunkDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceOutTrunk" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "VoiceOutTrunkCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceOutTrunk" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "VoiceOutTrunkCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "voice_out_trunks" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Outbound EU" }, "status": { "type": "string", "description": "Set to `blocked` to stop the trunk from placing calls.", "enum": [ "active", "blocked" ] }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous outbound calls. Null means no limit.", "minimum": 1, "maximum": 32767 }, "allow_any_did_as_cli": { "type": "boolean", "description": "Allow any DID the customer owns as the caller ID. While true the `dids` relationship is managed automatically and cannot be assigned." }, "on_cli_mismatch_action": { "type": "string", "description": "What to do when the caller ID is not one of the allowed DIDs.", "enum": [ "reject_call", "replace_cli", "send_original_cli", "randomize_cli" ] }, "default_dst_action": { "type": "string", "description": "Whether destinations not listed in `dst_prefixes` are allowed.", "enum": [ "allow_all", "reject_all" ] }, "dst_prefixes": { "type": "array", "description": "Destination prefixes the `default_dst_action` is inverted for, as digits without a leading `+` or any separator. Repeated prefixes are accepted and stored once.", "items": { "type": "string", "example": "4420" } }, "media_encryption_mode": { "type": "string", "description": "Media encryption required of the trunk.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "allowed_rtp_ips": { "type": "array", "nullable": true, "description": "Restrict RTP to these addresses. Null means no restriction.", "maxItems": 60, "uniqueItems": true, "items": { "type": "string" } }, "force_symmetric_rtp": { "type": "boolean", "description": "Learn the remote RTP address from arriving packets." }, "rtp_ping": { "type": "boolean", "description": "Send RTP keep-alives." }, "rtp_timeout": { "type": "integer", "description": "Drop the call after this many seconds of RTP silence.", "minimum": 30, "maximum": 600 }, "threshold_amount": { "type": "string", "description": "Spending on the trunk that triggers a notification, as a decimal string. The accepted range depends on the account.", "example": "100.00" }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the spending threshold is reached. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "emergency_enable_all": { "type": "boolean", "description": "Allow emergency calls from any DID the customer owns. While true the `emergency_dids` relationship cannot be assigned." }, "authentication_method": { "description": "How DIDWW authenticates calls from the trunk. `attributes` is determined by `type`: `credentials_and_ip` returns the generated `username` / `password` alongside the allowed addresses, `ip_only` authenticates by address alone, and `twilio` trusts a Twilio account SID. Sending it replaces the whole method.", "anyOf": [ { "$ref": "#/components/schemas/CredentialsAndIpAuthenticationRequest" }, { "$ref": "#/components/schemas/IpOnlyAuthenticationRequest" }, { "$ref": "#/components/schemas/TwilioAuthenticationRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "credentials_and_ip": "#/components/schemas/CredentialsAndIpAuthenticationRequest", "ip_only": "#/components/schemas/IpOnlyAuthenticationRequest", "twilio": "#/components/schemas/TwilioAuthenticationRequest" } } } }, "required": [ "name", "authentication_method", "on_cli_mismatch_action" ] }, "relationships": { "type": "object", "properties": { "default_did": { "type": "object", "description": "DID used as the caller ID. Required while `on_cli_mismatch_action` is `replace_cli`, and rejected otherwise. Only accepted on accounts with the `replace_cli` feature.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DidIdentifierNullable" } } }, "dids": { "type": "object", "description": "DIDs allowed as the caller ID. Rejected while `allow_any_did_as_cli` is true.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } }, "emergency_dids": { "type": "object", "description": "DIDs allowed to place emergency calls. Rejected while `emergency_enable_all` is true.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } } } } } } } }, "VoiceOutTrunkUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "voice_out_trunks" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "example": "Outbound EU" }, "status": { "type": "string", "description": "Set to `blocked` to stop the trunk from placing calls.", "enum": [ "active", "blocked" ] }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the trunk.", "maxLength": 100 }, "capacity_limit": { "type": "integer", "nullable": true, "description": "Maximum simultaneous outbound calls. Null means no limit.", "minimum": 1, "maximum": 32767 }, "allow_any_did_as_cli": { "type": "boolean", "description": "Allow any DID the customer owns as the caller ID. While true the `dids` relationship is managed automatically and cannot be assigned." }, "on_cli_mismatch_action": { "type": "string", "description": "What to do when the caller ID is not one of the allowed DIDs.", "enum": [ "reject_call", "replace_cli", "send_original_cli", "randomize_cli" ] }, "default_dst_action": { "type": "string", "description": "Whether destinations not listed in `dst_prefixes` are allowed.", "enum": [ "allow_all", "reject_all" ] }, "dst_prefixes": { "type": "array", "description": "Destination prefixes the `default_dst_action` is inverted for, as digits without a leading `+` or any separator. Repeated prefixes are accepted and stored once.", "items": { "type": "string", "example": "4420" } }, "media_encryption_mode": { "type": "string", "description": "Media encryption required of the trunk.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "allowed_rtp_ips": { "type": "array", "nullable": true, "description": "Restrict RTP to these addresses. Null means no restriction.", "maxItems": 60, "uniqueItems": true, "items": { "type": "string" } }, "force_symmetric_rtp": { "type": "boolean", "description": "Learn the remote RTP address from arriving packets." }, "rtp_ping": { "type": "boolean", "description": "Send RTP keep-alives." }, "rtp_timeout": { "type": "integer", "description": "Drop the call after this many seconds of RTP silence.", "minimum": 30, "maximum": 600 }, "threshold_amount": { "type": "string", "description": "Spending on the trunk that triggers a notification, as a decimal string. The accepted range depends on the account.", "example": "100.00" }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the spending threshold is reached. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "emergency_enable_all": { "type": "boolean", "description": "Allow emergency calls from any DID the customer owns. While true the `emergency_dids` relationship cannot be assigned." }, "authentication_method": { "description": "How DIDWW authenticates calls from the trunk. `attributes` is determined by `type`: `credentials_and_ip` returns the generated `username` / `password` alongside the allowed addresses, `ip_only` authenticates by address alone, and `twilio` trusts a Twilio account SID. Sending it replaces the whole method.", "anyOf": [ { "$ref": "#/components/schemas/CredentialsAndIpAuthenticationRequest" }, { "$ref": "#/components/schemas/IpOnlyAuthenticationRequest" }, { "$ref": "#/components/schemas/TwilioAuthenticationRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "credentials_and_ip": "#/components/schemas/CredentialsAndIpAuthenticationRequest", "ip_only": "#/components/schemas/IpOnlyAuthenticationRequest", "twilio": "#/components/schemas/TwilioAuthenticationRequest" } } } } }, "relationships": { "type": "object", "properties": { "default_did": { "type": "object", "description": "DID used as the caller ID. Required while `on_cli_mismatch_action` is `replace_cli`, and rejected otherwise. Only accepted on accounts with the `replace_cli` feature.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DidIdentifierNullable" } } }, "dids": { "type": "object", "description": "DIDs allowed as the caller ID. Rejected while `allow_any_did_as_cli` is true.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } }, "emergency_dids": { "type": "object", "description": "DIDs allowed to place emergency calls. Rejected while `emergency_enable_all` is true.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } } } } } } } }, "CredentialsAndIpAuthentication": { "type": "object", "description": "SIP digest credentials generated by DIDWW, plus an address allowlist.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "credentials_and_ip" ] }, "attributes": { "type": "object", "properties": { "allowed_sip_ips": { "type": "array", "description": "Addresses calls are accepted from. Required when this authentication method is sent, and never empty.", "minItems": 1, "uniqueItems": true, "maxItems": 60, "items": { "type": "string", "example": "203.0.113.10" } }, "tech_prefix": { "type": "string", "nullable": true, "description": "Prefix stripped from the dialled number before routing. Digits and `#` only, and rejected when the authentication method is the Twilio one.", "maxLength": 8, "pattern": "^[0-9#]+$" }, "username": { "type": "string", "description": "Generated SIP username. Read-only.", "readOnly": true }, "password": { "type": "string", "description": "Generated SIP password. Read-only.", "readOnly": true } }, "required": [ "allowed_sip_ips", "tech_prefix", "username", "password" ] } } }, "IpOnlyAuthentication": { "type": "object", "description": "Address allowlist only, and not selectable on a create: a trunk is created with `credentials_and_ip` or `twilio`. The allowlist is read-only once set.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "ip_only" ] }, "attributes": { "type": "object", "properties": { "allowed_sip_ips": { "type": "array", "description": "Addresses calls are accepted from. Required when this authentication method is sent, and never empty.", "minItems": 1, "uniqueItems": true, "maxItems": 60, "items": { "type": "string", "example": "203.0.113.10" } }, "tech_prefix": { "type": "string", "nullable": true, "description": "Prefix stripped from the dialled number before routing. Digits and `#` only, and rejected when the authentication method is the Twilio one.", "maxLength": 8, "pattern": "^[0-9#]+$" } }, "required": [ "allowed_sip_ips", "tech_prefix" ] } } }, "TwilioAuthentication": { "type": "object", "description": "A Twilio Elastic SIP Trunking account SID.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "twilio" ] }, "attributes": { "type": "object", "properties": { "twilio_account_sid": { "type": "string", "description": "The Twilio account SID. Required when this authentication method is sent, and unique across DIDWW.", "pattern": "^[a-zA-Z]{2}[0-9a-fA-F]{32}$", "example": "AC0123456789abcdef0123456789abcdef" } }, "required": [ "twilio_account_sid" ] } } }, "CredentialsAndIpAuthenticationRequest": { "type": "object", "description": "SIP digest credentials generated by DIDWW, plus an address allowlist.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "credentials_and_ip" ] }, "attributes": { "type": "object", "properties": { "allowed_sip_ips": { "type": "array", "description": "Addresses calls are accepted from. Required when this authentication method is sent, and never empty.", "minItems": 1, "uniqueItems": true, "maxItems": 60, "items": { "type": "string", "example": "203.0.113.10" } }, "tech_prefix": { "type": "string", "nullable": true, "description": "Prefix stripped from the dialled number before routing. Digits and `#` only, and rejected when the authentication method is the Twilio one.", "maxLength": 8, "pattern": "^[0-9#]+$" } } } } }, "IpOnlyAuthenticationRequest": { "type": "object", "description": "Address allowlist only, and not selectable on a create: a trunk is created with `credentials_and_ip` or `twilio`. The allowlist is read-only once set.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "ip_only" ] }, "attributes": { "type": "object", "properties": { "allowed_sip_ips": { "type": "array", "description": "Addresses calls are accepted from. Required when this authentication method is sent, and never empty.", "minItems": 1, "uniqueItems": true, "maxItems": 60, "items": { "type": "string", "example": "203.0.113.10" } }, "tech_prefix": { "type": "string", "nullable": true, "description": "Prefix stripped from the dialled number before routing. Digits and `#` only, and rejected when the authentication method is the Twilio one.", "maxLength": 8, "pattern": "^[0-9#]+$" } } } } }, "TwilioAuthenticationRequest": { "type": "object", "description": "A Twilio Elastic SIP Trunking account SID.", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "twilio" ] }, "attributes": { "type": "object", "properties": { "twilio_account_sid": { "type": "string", "description": "The Twilio account SID. Required when this authentication method is sent, and unique across DIDWW.", "pattern": "^[a-zA-Z]{2}[0-9a-fA-F]{32}$", "example": "AC0123456789abcdef0123456789abcdef" } } } } }, "VoiceOutTrunkRegenerateCredential": { "type": "object", "description": "A credential rotation for an outbound voice trunk.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "voice_out_trunk_regenerate_credentials" ] } } }, "VoiceOutTrunkRegenerateCredentialDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceOutTrunkRegenerateCredential" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "VoiceOutTrunkRegenerateCredentialCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "voice_out_trunk_regenerate_credentials" ] }, "relationships": { "type": "object", "properties": { "voice_out_trunk": { "type": "object", "description": "The trunk whose credentials to rotate. Only trunks authenticated with `credentials_and_ip` have credentials to rotate.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/VoiceOutTrunkIdentifier" } } } }, "required": [ "voice_out_trunk" ] } } } } }, "Identity": { "type": "object", "description": "The person or company a regulated number is registered to. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "identities" ] }, "attributes": { "type": "object", "required": [ "identity_type", "first_name", "last_name", "phone_number", "contact_email", "company_name", "company_reg_number", "vat_id", "id_number", "personal_tax_id", "birth_date", "description", "external_reference_id", "created_at", "verified" ], "properties": { "identity_type": { "type": "string", "description": "Whether the number is registered to a person or to a company.", "enum": [ "personal", "business" ] }, "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "phone_number": { "type": "string", "description": "Contact number, digits only.", "example": "442037691880" }, "contact_email": { "type": "string", "format": "email", "nullable": true, "example": "jane@example.com" }, "company_name": { "type": "string", "nullable": true, "description": "Required for a business identity, and rejected on a personal one." }, "company_reg_number": { "type": "string", "nullable": true, "description": "Company registration number. Rejected on a personal identity." }, "vat_id": { "type": "string", "nullable": true, "description": "VAT identification number. Rejected on a personal identity, and validated against `country`, which must be set with it." }, "id_number": { "type": "string", "nullable": true, "description": "Personal identification document number." }, "personal_tax_id": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the identity.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "verified": { "type": "boolean", "description": "True once the identity is registered to at least one DID — not a statement about whether DIDWW has reviewed its documents.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "birth_country", "proofs", "addresses", "permanent_documents" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "birth_country": { "$ref": "#/components/schemas/CountryToOne" }, "proofs": { "$ref": "#/components/schemas/ProofToMany" }, "addresses": { "$ref": "#/components/schemas/AddressToMany" }, "permanent_documents": { "$ref": "#/components/schemas/PermanentSupportingDocumentToMany" } } } } }, "IdentityDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Identity" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "IdentityCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Identity" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "IdentityCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "identities" ] }, "attributes": { "type": "object", "properties": { "identity_type": { "type": "string", "description": "Whether the number is registered to a person or to a company.", "enum": [ "personal", "business" ] }, "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "phone_number": { "type": "string", "description": "Contact number, digits only.", "example": "442037691880" }, "contact_email": { "type": "string", "format": "email", "nullable": true, "example": "jane@example.com" }, "company_name": { "type": "string", "nullable": true, "description": "Required for a business identity, and rejected on a personal one." }, "company_reg_number": { "type": "string", "nullable": true, "description": "Company registration number. Rejected on a personal identity." }, "vat_id": { "type": "string", "nullable": true, "description": "VAT identification number. Rejected on a personal identity, and validated against `country`, which must be set with it." }, "id_number": { "type": "string", "nullable": true, "description": "Personal identification document number." }, "personal_tax_id": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the identity.", "maxLength": 100 } }, "required": [ "identity_type", "first_name", "last_name", "phone_number" ] }, "relationships": { "type": "object", "properties": { "country": { "type": "object", "description": "Country the identity is registered in.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CountryIdentifierNullable" } } }, "birth_country": { "type": "object", "description": "Country of birth. Required where the address requirement asks for it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CountryIdentifierNullable" } } } } } } } } }, "IdentityUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "identities" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "phone_number": { "type": "string", "description": "Contact number, digits only.", "example": "442037691880" }, "contact_email": { "type": "string", "format": "email", "nullable": true, "example": "jane@example.com" }, "company_name": { "type": "string", "nullable": true, "description": "Required for a business identity, and rejected on a personal one." }, "company_reg_number": { "type": "string", "nullable": true, "description": "Company registration number. Rejected on a personal identity." }, "vat_id": { "type": "string", "nullable": true, "description": "VAT identification number. Rejected on a personal identity, and validated against `country`, which must be set with it." }, "id_number": { "type": "string", "nullable": true, "description": "Personal identification document number." }, "personal_tax_id": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the identity.", "maxLength": 100 } } }, "relationships": { "type": "object", "properties": { "country": { "type": "object", "description": "Country the identity is registered in.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CountryIdentifierNullable" } } }, "birth_country": { "type": "object", "description": "Country of birth. Required where the address requirement asks for it.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CountryIdentifierNullable" } } } } } } } } }, "Address": { "type": "object", "description": "A postal address of an identity, used to register regulated numbers. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "addresses" ] }, "attributes": { "type": "object", "required": [ "address", "city_name", "postal_code", "description", "external_reference_id", "created_at", "verified" ], "properties": { "address": { "type": "string", "description": "Street address.", "maxLength": 200, "example": "10 Downing Street" }, "city_name": { "type": "string", "example": "London" }, "postal_code": { "type": "string", "example": "SW1A 2AA" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the address.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "verified": { "type": "boolean", "description": "True once the address is registered to at least one DID — not a statement about whether DIDWW has reviewed its proofs.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "identity", "country", "area", "city", "proofs" ], "properties": { "identity": { "$ref": "#/components/schemas/IdentityToOne" }, "country": { "$ref": "#/components/schemas/CountryToOne" }, "area": { "$ref": "#/components/schemas/AreaToOne" }, "city": { "$ref": "#/components/schemas/CityToOne" }, "proofs": { "$ref": "#/components/schemas/ProofToMany" } } } } }, "AddressDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Address" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AddressCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "AddressCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "addresses" ] }, "attributes": { "type": "object", "properties": { "address": { "type": "string", "description": "Street address.", "maxLength": 200, "example": "10 Downing Street" }, "city_name": { "type": "string", "example": "London" }, "postal_code": { "type": "string", "example": "SW1A 2AA" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the address.", "maxLength": 100 } }, "required": [ "address", "city_name", "postal_code" ] }, "relationships": { "type": "object", "properties": { "identity": { "type": "object", "description": "Identity the address belongs to.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IdentityIdentifier" } } }, "country": { "type": "object", "description": "Country the address is in.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CountryIdentifier" } } } }, "required": [ "identity", "country" ] } } } } }, "AddressUpdateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "addresses" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "address": { "type": "string", "description": "Street address.", "maxLength": 200, "example": "10 Downing Street" }, "city_name": { "type": "string", "example": "London" }, "postal_code": { "type": "string", "example": "SW1A 2AA" }, "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the address.", "maxLength": 100 } } } } } } }, "ProofType": { "type": "object", "description": "A kind of document accepted as a proof. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "proof_types" ] }, "attributes": { "type": "object", "required": [ "name", "entity_type" ], "properties": { "name": { "type": "string", "example": "Passport", "readOnly": true }, "entity_type": { "type": "string", "description": "What the document proves — an identity or an address.", "enum": [ "Address", "Business", "Personal" ], "readOnly": true } } } } }, "ProofTypeDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/ProofType" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ProofTypeCollectionDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProofType" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Proof": { "type": "object", "description": "A document proving an identity or an address. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "proofs" ] }, "attributes": { "type": "object", "required": [ "created_at", "expires_at", "external_reference_id" ], "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the document stops being accepted. Null means it does not expire.", "readOnly": true }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the proof.", "maxLength": 100 } } }, "relationships": { "type": "object", "required": [ "proof_type", "entity" ], "properties": { "proof_type": { "$ref": "#/components/schemas/ProofTypeToOne" }, "entity": { "$ref": "#/components/schemas/ProofEntityToOne" } } } } }, "ProofDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Proof" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ProofCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Proof" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "ProofCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "proofs" ] }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } }, "relationships": { "type": "object", "properties": { "proof_type": { "type": "object", "description": "What kind of document this is.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProofTypeIdentifier" } } }, "entity": { "type": "object", "description": "The identity or address being proved. `type` must be `identities` or `addresses`, matching what the `proof_type` proves.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProofEntityIdentifier" } } }, "files": { "type": "object", "description": "Previously uploaded /encrypted_files holding the document. Write-only: the files are copied onto the proof and are not returned by reads.", "required": [ "data" ], "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/EncryptedFileIdentifier" } } } } }, "required": [ "proof_type", "entity", "files" ] } } } } }, "ProofUpdateRequest": { "type": "object", "description": "Only the external reference of a proof can be changed. Replace the document by deleting the proof and creating a new one.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "proofs" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } }, "SupportingDocumentTemplate": { "type": "object", "description": "A blank form to fill in and submit as a supporting document. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "supporting_document_templates" ] }, "attributes": { "type": "object", "required": [ "name", "permanent", "url" ], "properties": { "name": { "type": "string", "example": "Letter of Authorization", "readOnly": true }, "permanent": { "type": "boolean", "description": "True when the completed form stays on file (a permanent_supporting_document); false when it is submitted per address verification.", "readOnly": true }, "url": { "type": "string", "description": "Download URL of the blank form.", "readOnly": true } } } } }, "SupportingDocumentTemplateDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SupportingDocumentTemplateCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SupportingDocumentTemplate" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "PermanentSupportingDocument": { "type": "object", "description": "A completed supporting document kept on file against an identity. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "permanent_supporting_documents" ] }, "attributes": { "type": "object", "required": [ "created_at", "external_reference_id" ], "properties": { "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the document.", "maxLength": 100 } } }, "relationships": { "type": "object", "required": [ "template", "identity" ], "properties": { "template": { "$ref": "#/components/schemas/SupportingDocumentTemplateToOne" }, "identity": { "$ref": "#/components/schemas/IdentityToOne" } } } } }, "PermanentSupportingDocumentDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PermanentSupportingDocument" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "PermanentSupportingDocumentCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PermanentSupportingDocument" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "PermanentSupportingDocumentCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "permanent_supporting_documents" ] }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } }, "relationships": { "type": "object", "properties": { "template": { "type": "object", "description": "The blank form this document completes.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/SupportingDocumentTemplateIdentifier" } } }, "identity": { "type": "object", "description": "Identity the document belongs to.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IdentityIdentifier" } } }, "files": { "type": "object", "description": "Previously uploaded /encrypted_files holding the completed document. Write-only: the files are copied onto the document and are not returned by reads.", "required": [ "data" ], "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "$ref": "#/components/schemas/EncryptedFileIdentifier" } } } } }, "required": [ "template", "identity", "files" ] } } } } }, "PermanentSupportingDocumentUpdateRequest": { "type": "object", "description": "Only the external reference of a document can be changed. Replace the content by creating a new document for the same identity and template; it supersedes the previous one.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "permanent_supporting_documents" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } }, "EncryptedFile": { "type": "object", "description": "An encrypted file staged for use as a regulation document. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "encrypted_files" ] }, "attributes": { "type": "object", "required": [ "description", "expires_at" ], "properties": { "description": { "type": "string", "nullable": true, "description": "Free-form customer note." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the staged file is deleted. Always 24 hours after upload, whether or not it has been attached to anything by then.", "readOnly": true } } } } }, "EncryptedFileDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EncryptedFile" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "EncryptedFileCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EncryptedFile" } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "EncryptedFileUploadRequest": { "type": "object", "description": "The upload, as multipart form data. Field names carry the `encrypted_files[...]` wrapper the endpoint expects.", "required": [ "encrypted_files[file]", "encrypted_files[encryption_fingerprint]" ], "properties": { "encrypted_files[file]": { "type": "string", "format": "binary", "description": "The encrypted file. At most 20 MB." }, "encrypted_files[encryption_fingerprint]": { "type": "string", "description": "Fingerprints of the key pair the file was encrypted with, joined by `:::`. They are computed from the keys /public_keys serves, not served by it." }, "encrypted_files[description]": { "type": "string", "description": "Free-form customer note." } } }, "AddressRequirement": { "type": "object", "description": "The registration rules for a country and DID group type. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "address_requirements" ] }, "attributes": { "type": "object", "required": [ "identity_type", "personal_area_level", "business_area_level", "address_area_level", "personal_proof_qty", "business_proof_qty", "address_proof_qty", "personal_mandatory_fields", "business_mandatory_fields", "service_description_required", "restriction_message" ], "properties": { "identity_type": { "type": "string", "description": "Which kind of identity the country accepts. `any` means either.", "enum": [ "any", "personal", "business" ], "readOnly": true }, "personal_area_level": { "type": "string", "nullable": true, "description": "How close to the number a personal identity must be located. Null when the country does not accept that kind of identity.", "enum": [ "world_wide", "country", null ], "readOnly": true }, "business_area_level": { "type": "string", "nullable": true, "description": "How close to the number a business identity must be located. Null when the country does not accept that kind of identity.", "enum": [ "world_wide", "country", null ], "readOnly": true }, "address_area_level": { "type": "string", "description": "How close to the number the address itself must be located.", "enum": [ "world_wide", "country", "area", "city" ], "readOnly": true }, "personal_proof_qty": { "type": "integer", "description": "Proofs required of a personal identity.", "readOnly": true }, "business_proof_qty": { "type": "integer", "description": "Proofs required of a business identity.", "readOnly": true }, "address_proof_qty": { "type": "integer", "description": "Proofs required of the address.", "readOnly": true }, "personal_mandatory_fields": { "type": "array", "nullable": true, "description": "Identity fields that must be filled in for a personal identity. Null when none are.", "items": { "type": "string", "enum": [ "birth_date", "birth_country", "country", "personal_tax_id", "id_number", "vat_id", "company_reg_number", "contact_email" ] }, "readOnly": true }, "business_mandatory_fields": { "type": "array", "nullable": true, "description": "Identity fields that must be filled in for a business identity. Null when none are.", "items": { "type": "string", "enum": [ "birth_date", "birth_country", "country", "personal_tax_id", "id_number", "vat_id", "company_reg_number", "contact_email" ] }, "readOnly": true }, "service_description_required": { "type": "boolean", "description": "True when the address verification must describe how the number will be used.", "readOnly": true }, "restriction_message": { "type": "string", "description": "Restrictions the country places on these numbers.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "did_group_type", "personal_permanent_document", "business_permanent_document", "personal_onetime_document", "business_onetime_document", "personal_proof_types", "business_proof_types", "address_proof_types" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "did_group_type": { "$ref": "#/components/schemas/DidGroupTypeToOne" }, "personal_permanent_document": { "$ref": "#/components/schemas/SupportingDocumentTemplateToOne" }, "business_permanent_document": { "$ref": "#/components/schemas/SupportingDocumentTemplateToOne" }, "personal_onetime_document": { "$ref": "#/components/schemas/SupportingDocumentTemplateToOne" }, "business_onetime_document": { "$ref": "#/components/schemas/SupportingDocumentTemplateToOne" }, "personal_proof_types": { "$ref": "#/components/schemas/ProofTypeToMany" }, "business_proof_types": { "$ref": "#/components/schemas/ProofTypeToMany" }, "address_proof_types": { "$ref": "#/components/schemas/ProofTypeToMany" } } } } }, "AddressRequirementDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AddressRequirement" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AddressRequirementCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressRequirement" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "AddressRequirementValidation": { "type": "object", "description": "The result of checking an identity and/or address against an address requirement. Carries no fields: success is the 201 itself, failure is a 422 naming what is missing.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "address_requirement_validations" ] } } }, "AddressRequirementValidationDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AddressRequirementValidation" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AddressRequirementValidationCreateRequest": { "type": "object", "description": "At least one of `identity` and `address` must be sent. When both are, the address must belong to the identity.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "address_requirement_validations" ] }, "relationships": { "type": "object", "properties": { "address_requirement": { "type": "object", "description": "Requirement to check against.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressRequirementIdentifier" } } }, "identity": { "type": "object", "description": "Identity to check.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IdentityIdentifierNullable" } } }, "address": { "type": "object", "description": "Address to check.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressIdentifierNullable" } } } }, "required": [ "address_requirement" ], "anyOf": [ { "required": [ "identity" ] }, { "required": [ "address" ] } ] } } } } }, "AddressVerification": { "type": "object", "description": "A submission asking DIDWW to approve an address for a set of DIDs. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "address_verifications" ] }, "attributes": { "type": "object", "required": [ "reference", "status", "reject_reasons", "reject_comment", "service_description", "callback_url", "callback_method", "external_reference_id", "created_at" ], "properties": { "reference": { "type": "string", "description": "Human-readable reference.", "example": "AV-1234", "readOnly": true }, "status": { "type": "string", "description": "`pending` until DIDWW has reviewed the submission.", "enum": [ "pending", "approved", "rejected" ], "readOnly": true }, "reject_reasons": { "type": "array", "nullable": true, "description": "Why the submission was rejected. Null unless `status` is `rejected`.", "items": { "type": "string" }, "readOnly": true }, "reject_comment": { "type": "string", "nullable": true, "description": "Free-form note from the reviewer.", "readOnly": true }, "service_description": { "type": "string", "nullable": true, "description": "How the numbers will be used. Required where the address requirement says so." }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the status changes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the verification.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "address", "dids" ], "properties": { "address": { "$ref": "#/components/schemas/AddressToOne" }, "dids": { "$ref": "#/components/schemas/DidToMany" } } } } }, "AddressVerificationDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/AddressVerification" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "AddressVerificationCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AddressVerification" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "AddressVerificationCreateRequest": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "address_verifications" ] }, "attributes": { "type": "object", "properties": { "service_description": { "type": "string", "nullable": true, "description": "How the numbers will be used. Required where the address requirement says so." }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the status changes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed. Send `callback_url` and `callback_method` together: one without the other is rejected.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback. Send `callback_url` and `callback_method` together: one without the other is rejected." }, "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } }, "anyOf": [ { "required": [ "callback_url", "callback_method" ] }, { "not": { "anyOf": [ { "required": [ "callback_url" ] }, { "required": [ "callback_method" ] } ] } } ] }, "relationships": { "type": "object", "properties": { "address": { "type": "object", "description": "Address to get approved.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressIdentifier" } } }, "dids": { "type": "object", "description": "DIDs to register against the address.", "required": [ "data" ], "properties": { "data": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } }, "onetime_files": { "type": "object", "description": "Previously uploaded /encrypted_files holding the one-time supporting documents the requirement asks for. Write-only: the files are copied onto the verification and are not returned by reads.", "required": [ "data" ], "properties": { "data": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/EncryptedFileIdentifier" } } } } }, "required": [ "address", "dids" ] } } } } }, "AddressVerificationUpdateRequest": { "type": "object", "description": "Only the external reference can be changed. A rejected verification is replaced by creating a new one.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "address_verifications" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } }, "EmergencyRequirement": { "type": "object", "description": "The rules for activating emergency calling in a country, for a DID group type. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "emergency_requirements" ] }, "attributes": { "type": "object", "required": [ "identity_type", "personal_area_level", "business_area_level", "address_area_level", "personal_mandatory_fields", "business_mandatory_fields", "address_mandatory_fields", "estimate_setup_time", "requirement_restriction_message" ], "properties": { "identity_type": { "type": "string", "description": "Which kind of identity the country accepts. `any` means either.", "enum": [ "any", "business", "personal" ], "readOnly": true }, "personal_area_level": { "type": "string", "nullable": true, "description": "How close to the number a personal identity must be located. Null when the country does not accept that kind of identity.", "enum": [ "world_wide", "country", null ], "readOnly": true }, "business_area_level": { "type": "string", "nullable": true, "description": "How close to the number a business identity must be located. Null when the country does not accept that kind of identity.", "enum": [ "world_wide", "country", null ], "readOnly": true }, "address_area_level": { "type": "string", "description": "How close to the number the registered address must be located.", "enum": [ "country", "area", "city" ], "readOnly": true }, "personal_mandatory_fields": { "type": "array", "description": "Fields that must be filled in for a personal identity. Empty when none are. Human-readable labels, not API names.", "items": { "type": "string", "enum": [ "Birth Date", "Country of Tax Residence", "ID Number", "Personal Tax ID", "Contact email" ] }, "readOnly": true }, "business_mandatory_fields": { "type": "array", "description": "Fields that must be filled in for a business identity. Empty when none are. Human-readable labels, not API names.", "items": { "type": "string", "enum": [ "ID Number", "VAT Number / TAX Code", "Country of Tax Residence", "Company ID", "Representative Tax ID", "Contact email", "Company Representative Date of Birth" ] }, "readOnly": true }, "address_mandatory_fields": { "type": "array", "description": "Fields that must be filled in for the address. Empty when none are. Human-readable labels, not API names.", "items": { "type": "string", "enum": [ "State/Province/Region" ] }, "readOnly": true }, "estimate_setup_time": { "type": "string", "description": "How long activation usually takes.", "example": "3 business days", "readOnly": true }, "requirement_restriction_message": { "type": "string", "nullable": true, "description": "Restrictions the country places on emergency calling.", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "did_group_type" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "did_group_type": { "$ref": "#/components/schemas/DidGroupTypeToOne" } } }, "meta": { "type": "object", "properties": { "setup_price": { "type": "string", "nullable": true, "description": "One-off activation charge, as a decimal string. Always `\"0.0\"` when priced. Null only on a requirement reached through an emergency calling service this account is no longer priced for." }, "monthly_price": { "type": "string", "nullable": true, "description": "Recurring monthly charge, as a decimal string. Null only on a requirement reached through an emergency calling service this account is no longer priced for." } }, "required": [ "setup_price", "monthly_price" ] } } }, "EmergencyRequirementDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyRequirement" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "EmergencyRequirementCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyRequirement" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/Region" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "EmergencyRequirementValidation": { "type": "object", "description": "The result of checking an identity and/or address against an emergency requirement. Carries no fields: success is the 201 itself, failure is a 422 naming what is missing.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "emergency_requirement_validations" ] } } }, "EmergencyRequirementValidationDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyRequirementValidation" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "EmergencyRequirementValidationCreateRequest": { "type": "object", "description": "At least one of `identity` and `address` must be sent. When both are, the address must belong to the identity.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "emergency_requirement_validations" ] }, "relationships": { "type": "object", "properties": { "emergency_requirement": { "type": "object", "description": "Requirement to check against.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyRequirementIdentifier" } } }, "identity": { "type": "object", "description": "Identity to check.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/IdentityIdentifierNullable" } } }, "address": { "type": "object", "description": "Address to check.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressIdentifierNullable" } } } }, "required": [ "emergency_requirement" ], "anyOf": [ { "required": [ "identity" ] }, { "required": [ "address" ] } ] } } } } }, "EmergencyCallingService": { "type": "object", "description": "An emergency calling subscription, created by an order and cancelled by DELETE. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships", "meta" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "emergency_calling_services" ] }, "attributes": { "type": "object", "required": [ "name", "reference", "status", "activated_at", "canceled_at", "renew_date", "created_at" ], "properties": { "name": { "type": "string", "example": "London emergency", "readOnly": true }, "reference": { "type": "string", "description": "Human-readable reference.", "example": "ECS-1234", "readOnly": true }, "status": { "type": "string", "description": "Lifecycle state of the subscription.", "enum": [ "active", "canceled", "new", "changes_required", "in_process", "pending_update" ], "readOnly": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "canceled_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "renew_date": { "type": "string", "format": "date", "nullable": true, "description": "Next renewal date. Null once cancelled.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "country", "did_group_type", "order", "emergency_requirement", "emergency_verification", "dids" ], "properties": { "country": { "$ref": "#/components/schemas/CountryToOne" }, "did_group_type": { "$ref": "#/components/schemas/DidGroupTypeToOne" }, "order": { "$ref": "#/components/schemas/OrderToOne" }, "emergency_requirement": { "$ref": "#/components/schemas/EmergencyRequirementToOne" }, "emergency_verification": { "$ref": "#/components/schemas/EmergencyVerificationToOne" }, "dids": { "$ref": "#/components/schemas/DidToMany" } } }, "meta": { "type": "object", "properties": { "setup_price": { "type": "string", "description": "One-off activation charge, as a decimal string.", "example": "10.00" }, "monthly_price": { "type": "string", "description": "Recurring monthly charge, as a decimal string.", "example": "5.00" } }, "required": [ "setup_price", "monthly_price" ] } } }, "EmergencyCallingServiceDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyCallingService" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "EmergencyCallingServiceCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyCallingService" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "EmergencyVerification": { "type": "object", "description": "A submission registering an address for an emergency calling service. Describes the full resource: a response to a request carrying `fields[...]` omits the members it did not ask for.", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "type": { "type": "string", "enum": [ "emergency_verifications" ] }, "attributes": { "type": "object", "required": [ "reference", "status", "reject_reasons", "reject_comment", "callback_url", "callback_method", "external_reference_id", "created_at" ], "properties": { "reference": { "type": "string", "description": "Human-readable reference.", "example": "XKQ-004821", "readOnly": true }, "status": { "type": "string", "description": "`pending` until DIDWW has reviewed the submission.", "enum": [ "approved", "pending", "rejected" ], "readOnly": true }, "reject_reasons": { "type": "array", "nullable": true, "description": "Why the submission was rejected. Null unless `status` is `rejected`.", "items": { "type": "string" }, "readOnly": true }, "reject_comment": { "type": "string", "nullable": true, "description": "Free-form note from the reviewer.", "readOnly": true }, "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the status changes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback." }, "external_reference_id": { "type": "string", "nullable": true, "description": "Customer's own identifier for the verification.", "maxLength": 100 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "relationships": { "type": "object", "required": [ "address", "emergency_calling_service", "dids" ], "properties": { "address": { "$ref": "#/components/schemas/AddressToOne" }, "emergency_calling_service": { "$ref": "#/components/schemas/EmergencyCallingServiceToOne" }, "dids": { "$ref": "#/components/schemas/DidToMany" } } } } }, "EmergencyVerificationDocument": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyVerification" }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "EmergencyVerificationCollectionDocument": { "type": "object", "required": [ "data", "meta", "links" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmergencyVerification" } }, "included": { "type": "array", "description": "Compound document. Present only when `include` was sent.", "items": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "$ref": "#/components/schemas/AddressRequirement" }, { "$ref": "#/components/schemas/AddressVerification" }, { "$ref": "#/components/schemas/Area" }, { "$ref": "#/components/schemas/CapacityPool" }, { "$ref": "#/components/schemas/City" }, { "$ref": "#/components/schemas/Country" }, { "$ref": "#/components/schemas/Did" }, { "$ref": "#/components/schemas/DidGroup" }, { "$ref": "#/components/schemas/DidGroupType" }, { "$ref": "#/components/schemas/EmergencyCallingService" }, { "$ref": "#/components/schemas/EmergencyRequirement" }, { "$ref": "#/components/schemas/EmergencyVerification" }, { "$ref": "#/components/schemas/Identity" }, { "$ref": "#/components/schemas/Order" }, { "$ref": "#/components/schemas/PermanentSupportingDocument" }, { "$ref": "#/components/schemas/Pop" }, { "$ref": "#/components/schemas/Proof" }, { "$ref": "#/components/schemas/ProofType" }, { "$ref": "#/components/schemas/QtyBasedPricing" }, { "$ref": "#/components/schemas/Region" }, { "$ref": "#/components/schemas/SharedCapacityGroup" }, { "$ref": "#/components/schemas/StockKeepingUnit" }, { "$ref": "#/components/schemas/SupportingDocumentTemplate" }, { "$ref": "#/components/schemas/VoiceInTrunk" }, { "$ref": "#/components/schemas/VoiceInTrunkGroup" } ] } }, "meta": { "$ref": "#/components/schemas/CollectionMeta" }, "links": { "$ref": "#/components/schemas/PaginationLinks" } } }, "EmergencyVerificationCreateRequest": { "type": "object", "description": "Two modes, chosen by what is sent. Omit `emergency_calling_service` and send `dids` to activate emergency calling on those numbers, which creates the calling service too. Send `emergency_calling_service` without `dids` to register a different address against a subscription that already exists. Sending both is rejected.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "emergency_verifications" ] }, "attributes": { "type": "object", "properties": { "callback_url": { "type": "string", "nullable": true, "description": "URL notified when the status changes. A value with no scheme is accepted and read as `http://`; only `http` and `https` are allowed. Send `callback_url` and `callback_method` together: one without the other is rejected.", "format": "uri" }, "callback_method": { "type": "string", "nullable": true, "enum": [ "get", "post", null ], "description": "HTTP method used for the callback. Send `callback_url` and `callback_method` together: one without the other is rejected." }, "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } }, "anyOf": [ { "required": [ "callback_url", "callback_method" ] }, { "not": { "anyOf": [ { "required": [ "callback_url" ] }, { "required": [ "callback_method" ] } ] } } ] }, "relationships": { "type": "object", "properties": { "address": { "type": "object", "description": "Address to register.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AddressIdentifier" } } }, "dids": { "type": "object", "description": "DIDs to activate emergency calling on. Required when creating a new calling service, and rejected when `emergency_calling_service` is sent.", "required": [ "data" ], "properties": { "data": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/DidIdentifier" } } } }, "emergency_calling_service": { "type": "object", "description": "An existing subscription to re-verify with a different address. Send it without `dids`; omit it to create a new subscription.", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EmergencyCallingServiceIdentifier" } } } }, "required": [ "address" ], "oneOf": [ { "required": [ "dids" ], "not": { "required": [ "emergency_calling_service" ] } }, { "required": [ "emergency_calling_service" ], "not": { "required": [ "dids" ] } } ] } } } } }, "EmergencyVerificationUpdateRequest": { "type": "object", "description": "Only the external reference can be changed. A rejected verification is replaced by creating a new one.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "type" ], "properties": { "type": { "type": "string", "enum": [ "emergency_verifications" ] }, "id": { "type": "string", "format": "uuid", "example": "e5a4e2f1-3b26-4a5c-9a0a-2f7c1f3e8d10" }, "attributes": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Customer's own identifier.", "nullable": true, "maxLength": 100 } } } } } } } }, "parameters": { "ApiVersion": { "name": "X-DIDWW-Api-Version", "in": "header", "required": false, "description": "V3 API version to serve the request with. Defaults to the version configured for the API key's customer. A value this API does not know, and one older than that default, are both ignored rather than refused — the request is served by the default version. This document describes `2026-04-16`.", "example": "2026-04-16", "schema": { "type": "string", "format": "date" } }, "PageNumber": { "name": "page[number]", "in": "query", "required": false, "description": "1-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PublicKeyFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Accepted but not applied: every key is returned whatever is asked for. Accepts a comma-separated list, matching any of the values." } } } }, "PublicKeyFields": { "name": "fields[public_keys]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "key" ] } }, "example": [ "id", "key" ] }, "CountryFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Matches the country by its identifier. Accepts a comma-separated list, matching any of the values." }, "is_available": { "type": "boolean", "description": "Matches countries by whether DID numbers there can be bought right now." }, "iso": { "type": "string", "description": "Matches countries by ISO 3166-1 alpha-2 code. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches countries by name, case-insensitively. Accepts a comma-separated list, matching any of the values." }, "prefix": { "type": "string", "description": "Matches countries by international dialling prefix, written without a leading `+`. Accepts a comma-separated list, matching any of the values." } } } }, "CountrySort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "iso", "-iso", "name", "-name", "prefix", "-prefix" ] } }, "example": [ "iso" ] }, "CountryFields": { "name": "fields[countries]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "prefix", "iso", "regions" ] } }, "example": [ "id", "name" ] }, "RegionFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches regions of the country. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the region by its identifier. Accepts a comma-separated list, matching any of the values." }, "iso": { "type": "string", "description": "Matches regions by ISO 3166-2 subdivision code, country part included — `US-CA`, not `CA`. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches regions by name, case-insensitively. Accepts a comma-separated list, matching any of the values." } } } }, "RegionSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "iso", "-iso", "name", "-name" ] } }, "example": [ "iso" ] }, "RegionFields": { "name": "fields[regions]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "iso", "country" ] } }, "example": [ "id", "name" ] }, "CityFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "area.id": { "type": "string", "description": "Matches cities that belong to the regulatory area. Accepts a comma-separated list, matching any of the values." }, "country.id": { "type": "string", "description": "Matches cities that belong to the country. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the city by its identifier. Accepts a comma-separated list, matching any of the values." }, "is_available": { "type": "boolean", "description": "Matches cities by whether DID numbers there can be bought right now." }, "name": { "type": "string", "description": "Matches cities by name, case-insensitively. Accepts a comma-separated list, matching any of the values." }, "region.id": { "type": "string", "description": "Matches cities that belong to the region. Accepts a comma-separated list, matching any of the values." } } } }, "CitySort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "-name" ] } }, "example": [ "name" ] }, "CityPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, "CityFields": { "name": "fields[cities]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "country", "region", "area" ] } }, "example": [ "id", "name" ] }, "AreaFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches areas of the country. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the area by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches areas by name, case-insensitively. Accepts a comma-separated list, matching any of the values." } } } }, "AreaSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "-name" ] } }, "example": [ "name" ] }, "AreaPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000 } }, "AreaFields": { "name": "fields[areas]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "country" ] } }, "example": [ "id", "name" ] }, "PopFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Matches the point of presence by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "PopFields": { "name": "fields[pops]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name" ] } }, "example": [ "id", "name" ] }, "DidGroupTypeFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Matches the DID group type by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches DID group types by name. Accepts a comma-separated list, matching any of the values." } } } }, "DidGroupTypeSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "-name" ] } }, "example": [ "name" ] }, "DidGroupTypePageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "DidGroupTypeFields": { "name": "fields[did_group_types]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name" ] } }, "example": [ "id", "name" ] }, "DidGroupFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "allow_additional_channels": { "type": "boolean", "description": "Matches groups whose DIDs can take extra channels." }, "area_name": { "type": "string", "description": "Matches groups by area name, ignoring case. Accepts a comma-separated list, matching any of the values." }, "available_dids_enabled": { "type": "boolean", "description": "Matches groups whose individual numbers can be picked through /available_dids." }, "city.id": { "type": "string", "description": "Matches groups covering the city. Accepts a comma-separated list, matching any of the values." }, "country.id": { "type": "string", "description": "Matches groups covering the country. Accepts a comma-separated list, matching any of the values." }, "did_group_type.id": { "type": "string", "description": "Matches groups of the DID group type. Accepts a comma-separated list, matching any of the values." }, "features": { "type": "string", "description": "Matches groups offering all of the listed features. Accepts a comma-separated list; every listed value must be offered. Accepted values: `voice_in`, `voice_out`, `t38`, `sms_in`, `p2p`, `a2p`, `emergency`, `cnam_out`." }, "id": { "type": "string", "description": "Matches the DID group by its identifier. Accepts a comma-separated list, matching any of the values." }, "is_available": { "type": "boolean", "description": "Matches groups that can be ordered from right now, either from stock or on back order." }, "is_metered": { "type": "boolean", "description": "Matches groups whose inbound minutes are billed per minute." }, "meta.total_count_gteq": { "type": "integer", "description": "Matches groups holding at least this many numbers in stock." }, "nanpa_prefix.id": { "type": "string", "format": "uuid", "description": "Matches groups served by the NANPA prefix." }, "nanpa_prefix.npanxx": { "type": "string", "description": "Matches groups served by the NANPA prefix with this six-digit NPA-NXX. Accepts a comma-separated list, matching any of the values. An empty value is accepted." }, "needs_registration": { "type": "boolean", "description": "Matches groups where buying requires a verified address." }, "prefix": { "type": "string", "description": "Matches groups by their dialling prefix, without the country code — the value the `prefix` attribute carries. Accepts a comma-separated list, matching any of the values." }, "region.id": { "type": "string", "description": "Matches groups covering the region. Accepts a comma-separated list, matching any of the values." } } } }, "DidGroupSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "allow_additional_channels", "-allow_additional_channels", "area_name", "-area_name", "country.name", "-country.name", "did_group_type.name", "-did_group_type.name", "is_metered", "-is_metered", "prefix", "-prefix", "service_restrictions", "-service_restrictions" ] } }, "example": [ "allow_additional_channels" ] }, "DidGroupPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "DidGroupFields": { "name": "fields[did_groups]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "prefix", "area_name", "features", "is_metered", "allow_additional_channels", "service_restrictions", "country", "city", "did_group_type", "region", "stock_keeping_units", "address_requirement" ] } }, "example": [ "id", "prefix" ] }, "NanpaPrefixFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches prefixes assigned to the country. Accepts a comma-separated list, matching any of the values." }, "did_group.features": { "type": "string", "description": "Matches prefixes whose DID group offers the capability. Several values must all be offered by the same group. Accepts a comma-separated list; every listed value must be offered. Accepted values: `voice_in`, `voice_out`, `t38`, `sms_in`, `p2p`, `a2p`, `emergency`, `cnam_out`." }, "did_group.is_available": { "type": "boolean", "description": "Matches prefixes whose DID group has numbers in stock." }, "id": { "type": "string", "description": "Matches the NANPA prefix by its identifier. Accepts a comma-separated list, matching any of the values." }, "npa": { "type": "string", "description": "Matches prefixes with this area code. Accepts a comma-separated list, matching any of the values." }, "npanxx": { "type": "string", "description": "Matches prefixes whose area code and central office code, joined together, contain this value." }, "nxx": { "type": "string", "description": "Matches prefixes with this central office code. Accepts a comma-separated list, matching any of the values." }, "region.id": { "type": "string", "description": "Matches prefixes assigned to the region. Accepts a comma-separated list, matching any of the values." } } } }, "NanpaPrefixSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "npa", "-npa", "nxx", "-nxx" ] } }, "example": [ "npa" ] }, "NanpaPrefixPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "NanpaPrefixFields": { "name": "fields[nanpa_prefixes]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "npa", "nxx", "country", "region" ] } }, "example": [ "id", "npa" ] }, "AvailableDidFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "city.id": { "type": "string", "description": "Matches numbers whose DID group covers the city. Accepts a comma-separated list, matching any of the values." }, "country.id": { "type": "string", "description": "Matches numbers whose DID group covers the country. Accepts a comma-separated list, matching any of the values." }, "did_group.features": { "type": "string", "description": "Matches numbers whose DID group offers all of the listed features. Accepts a comma-separated list; every listed value must be offered. Accepted values: `voice_in`, `voice_out`, `t38`, `sms_in`, `p2p`, `a2p`, `emergency`, `cnam_out`." }, "did_group.id": { "type": "string", "description": "Matches numbers in the DID group. Accepts a comma-separated list, matching any of the values. An empty value is accepted." }, "did_group.needs_registration": { "type": "boolean", "description": "Matches numbers whose DID group requires a verified address before buying." }, "did_group_type.id": { "type": "string", "description": "Matches numbers whose DID group is of the DID group type. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the number by its identifier. Accepts a comma-separated list, matching any of the values." }, "nanpa_prefix.id": { "type": "string", "description": "Matches numbers carrying the NANPA prefix. Accepts a comma-separated list, matching any of the values." }, "number_contains": { "type": "string", "description": "Matches numbers containing this fragment. Fewer than three characters is rejected unless the request also filters by country, region, city or DID group." }, "region.id": { "type": "string", "description": "Matches numbers whose DID group covers the region. Accepts a comma-separated list, matching any of the values." } } } }, "AvailableDidFields": { "name": "fields[available_dids]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "number", "did_group", "nanpa_prefix" ] } }, "example": [ "id", "number" ] }, "DidReservationFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Matches DID reservations whose note contains the text. An empty value is accepted." }, "id": { "type": "string", "description": "Matches the DID reservation by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "DidReservationSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "description", "-description", "expire_at", "-expire_at", "expires_at", "-expires_at" ] } }, "example": [ "created_at" ] }, "DidReservationPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "DidReservationFields": { "name": "fields[did_reservations]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "description", "created_at", "expires_at", "available_did" ] } }, "example": [ "id", "description" ] }, "DidFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "address_verification.id": { "type": "string", "description": "Matches DIDs covered by the address verification. Accepts a comma-separated list, matching any of the values." }, "awaiting_registration": { "type": "boolean", "description": "Matches DIDs waiting for regulatory registration to complete." }, "billing_cycles_count": { "type": "string", "description": "Matches DIDs with this many billing cycles left before release. Accepts a comma-separated list, matching any of the values. An empty value is accepted." }, "blocked": { "type": "boolean", "description": "Matches DIDs that cannot carry traffic — blocked by the customer, blocked by DIDWW, or awaiting registration." }, "capacity_pool.id": { "type": "string", "description": "Matches DIDs drawing channels from the capacity pool. Accepts a comma-separated list, matching any of the values." }, "city.id": { "type": "string", "description": "Matches DIDs whose DID group belongs to the city. Accepts a comma-separated list, matching any of the values." }, "country.id": { "type": "string", "description": "Matches DIDs whose DID group belongs to the country. Accepts a comma-separated list, matching any of the values. An empty value is accepted." }, "description": { "type": "string", "description": "Matches DIDs whose description contains this value. An empty value is accepted." }, "did_group.features": { "type": "string", "description": "Matches DIDs whose DID group offers every listed service. Accepts a comma-separated list; every listed value must be offered. Accepted values: `voice_in`, `voice_out`, `t38`, `sms_in`, `p2p`, `a2p`, `emergency`, `cnam_out`." }, "did_group.id": { "type": "string", "description": "Matches DIDs belonging to the DID group. Accepts a comma-separated list, matching any of the values." }, "emergency_calling_service.id": { "type": "string", "description": "Matches DIDs assigned to the emergency calling service. Accepts a comma-separated list, matching any of the values." }, "emergency_enabled": { "type": "boolean", "description": "Matches DIDs that have emergency calling active." }, "id": { "type": "string", "description": "Matches the DID by its identifier. Accepts a comma-separated list, matching any of the values." }, "number": { "type": "string", "description": "Matches DIDs whose full number is exactly this value. Accepts a comma-separated list, matching any of the values." }, "order.id": { "type": "string", "description": "Matches DIDs that came from the order. Accepts a comma-separated list, matching any of the values." }, "order.reference": { "type": "string", "description": "Matches DIDs whose order carries this reference. Accepts a comma-separated list, matching any of the values." }, "region.id": { "type": "string", "description": "Matches DIDs whose DID group belongs to the region. Accepts a comma-separated list, matching any of the values." }, "shared_capacity_group.id": { "type": "string", "description": "Matches DIDs assigned to the shared capacity group. Accepts a comma-separated list, matching any of the values." }, "terminated": { "type": "boolean", "description": "Matches DIDs that have been cancelled." }, "trunk.id": { "type": "string", "description": "Matches DIDs routed to the voice_in_trunk. A legacy alias of `voice_in_trunk.id`. Accepts a comma-separated list, matching any of the values." }, "trunk_group.id": { "type": "string", "description": "Matches DIDs routed to the voice_in_trunk_group. A legacy alias of `voice_in_trunk_group.id`. Accepts a comma-separated list, matching any of the values." }, "voice_in_trunk.id": { "type": "string", "description": "Matches DIDs routed to the voice_in_trunk. Accepts a comma-separated list, matching any of the values." }, "voice_in_trunk_group.id": { "type": "string", "description": "Matches DIDs routed to the voice_in_trunk_group. Accepts a comma-separated list, matching any of the values." } } } }, "DidSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "awaiting_registration", "-awaiting_registration", "billing_cycles_count", "-billing_cycles_count", "blocked", "-blocked", "capacity_limit", "-capacity_limit", "channels_included_count", "-channels_included_count", "created_at", "-created_at", "dedicated_channels_count", "-dedicated_channels_count", "description", "-description", "expires_at", "-expires_at", "number", "-number", "terminated", "-terminated" ] } }, "example": [ "awaiting_registration" ] }, "DidPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "DidFields": { "name": "fields[dids]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "number", "description", "blocked", "awaiting_registration", "terminated", "emergency_enabled", "capacity_limit", "channels_included_count", "dedicated_channels_count", "billing_cycles_count", "created_at", "expires_at", "did_group", "order", "capacity_pool", "shared_capacity_group", "address_verification", "voice_in_trunk", "voice_in_trunk_group", "emergency_calling_service", "emergency_verification", "identity" ] } }, "example": [ "id", "number" ] }, "DidHistoryFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "action": { "type": "string", "description": "Matches entries recording this action.", "enum": [ "assigned", "renewed", "canceled", "removed", "billing_cycles_count_changed", "restored" ] }, "created_at_gteq": { "type": "string", "format": "date-time", "description": "Matches entries recorded at or after the given moment. A moment older than the retention window is rejected." }, "created_at_lteq": { "type": "string", "format": "date-time", "description": "Matches entries recorded at or before the given moment. A moment older than the retention window is rejected." }, "did_number": { "type": "string", "description": "Matches entries about this number, in E.164 without the leading `+`." }, "id": { "type": "string", "description": "Matches the entry by its identifier. Accepts a comma-separated list, matching any of the values." }, "method": { "type": "string", "description": "Matches entries made through this interface.", "enum": [ "system", "api2", "api3", "staff", "user_panel", "mcp" ] } } } }, "DidHistorySort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at" ] } }, "example": [ "created_at" ] }, "DidHistoryPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "DidHistoryFields": { "name": "fields[did_history]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "did_number", "action", "method", "created_at" ] } }, "example": [ "id", "did_number" ] }, "OrderFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "created_at_gteq": { "type": "string", "format": "date-time", "description": "Matches orders created at or after the given moment." }, "created_at_lteq": { "type": "string", "format": "date-time", "description": "Matches orders created no later than the end of the day the value falls in." }, "external_reference_id": { "type": "string", "description": "Matches orders carrying this customer's own identifier." }, "id": { "type": "string", "description": "Matches the order by its identifier. Accepts a comma-separated list, matching any of the values." }, "reference": { "type": "string", "description": "Matches orders by their full order reference. Accepts a comma-separated list, matching any of the values." }, "status": { "type": "string", "description": "Matches orders in this state. Accepts a comma-separated list, matching any of the values. Accepted values: `pending`, `completed`, `canceled`." } } } }, "OrderSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "amount", "-amount", "created_at", "-created_at", "external_reference_id", "-external_reference_id", "reference", "-reference", "status", "-status" ] } }, "example": [ "amount" ] }, "OrderPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "OrderFields": { "name": "fields[orders]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "reference", "description", "amount", "status", "created_at", "callback_url", "callback_method", "external_reference_id", "items" ] } }, "example": [ "id", "reference" ] }, "BalanceFields": { "name": "fields[balances]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "balance", "credit", "total_balance" ] } }, "example": [ "id", "balance" ] }, "ExportFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Matches exports carrying this customer's own identifier." }, "id": { "type": "string", "description": "Matches the export by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "ExportSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "external_reference_id", "-external_reference_id", "status", "-status" ] } }, "example": [ "created_at" ] }, "ExportPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ExportFields": { "name": "fields[exports]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "export_type", "status", "url", "filters", "callback_url", "callback_method", "external_reference_id", "created_at" ] } }, "example": [ "id", "export_type" ] }, "CapacityPoolFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches capacity pools whose countries cover the given country. Accepts a comma-separated list; the pool must cover every listed country." }, "has_unassigned_channels": { "type": "boolean", "description": "Matches capacity pools by whether channels are left to assign." }, "id": { "type": "string", "description": "Matches the capacity pool by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches capacity pools by their full name." } } } }, "CapacityPoolSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "assigned_channels_count", "-assigned_channels_count", "metered_rate", "-metered_rate", "minimum_limit", "-minimum_limit", "minimum_qty_per_order", "-minimum_qty_per_order", "monthly_price", "-monthly_price", "name", "-name", "renew_date", "-renew_date", "setup_price", "-setup_price", "total_channels_count", "-total_channels_count" ] } }, "example": [ "assigned_channels_count" ] }, "CapacityPoolPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "CapacityPoolFields": { "name": "fields[capacity_pools]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "renew_date", "total_channels_count", "assigned_channels_count", "minimum_limit", "minimum_qty_per_order", "setup_price", "monthly_price", "metered_rate", "countries", "shared_capacity_groups", "qty_based_pricings" ] } }, "example": [ "id", "name" ] }, "SharedCapacityGroupFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "capacity_pool.id": { "type": "string", "description": "Matches shared capacity groups drawing their channels from the capacity pool. Accepts a comma-separated list, matching any of the values." }, "external_reference_id": { "type": "string", "description": "Matches shared capacity groups carrying this customer's own identifier." }, "id": { "type": "string", "description": "Matches the shared capacity group by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches shared capacity groups by their full name. Accepts a comma-separated list, matching any of the values." } } } }, "SharedCapacityGroupSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "external_reference_id", "-external_reference_id", "metered_channels_count", "-metered_channels_count", "name", "-name", "shared_channels_count", "-shared_channels_count" ] } }, "example": [ "created_at" ] }, "SharedCapacityGroupPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "SharedCapacityGroupFields": { "name": "fields[shared_capacity_groups]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "shared_channels_count", "metered_channels_count", "external_reference_id", "created_at", "capacity_pool", "dids" ] } }, "example": [ "id", "name" ] }, "VoiceInTrunkFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "configuration.type": { "type": "string", "description": "Matches trunks with a configuration of this type. A type this API does not know matches nothing rather than being rejected. Accepts a comma-separated list, matching any of the values." }, "external_reference_id": { "type": "string", "description": "Matches trunks whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the trunk by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches trunks whose name is exactly this value. Accepts a comma-separated list, matching any of the values." } } } }, "VoiceInTrunkSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "capacity_limit", "-capacity_limit", "cli_format", "-cli_format", "cli_prefix", "-cli_prefix", "created_at", "-created_at", "description", "-description", "external_reference_id", "-external_reference_id", "name", "-name", "priority", "-priority", "ringing_timeout", "-ringing_timeout", "weight", "-weight" ] } }, "example": [ "capacity_limit" ] }, "VoiceInTrunkPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "VoiceInTrunkFields": { "name": "fields[voice_in_trunks]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "description", "external_reference_id", "priority", "weight", "capacity_limit", "cli_format", "cli_prefix", "ringing_timeout", "created_at", "configuration", "voice_in_trunk_group", "pop" ] } }, "example": [ "id", "name" ] }, "VoiceInTrunkGroupFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Matches groups whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the trunk group by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "VoiceInTrunkGroupSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "capacity_limit", "-capacity_limit", "created_at", "-created_at", "external_reference_id", "-external_reference_id", "name", "-name" ] } }, "example": [ "capacity_limit" ] }, "VoiceInTrunkGroupPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "VoiceInTrunkGroupFields": { "name": "fields[voice_in_trunk_groups]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "capacity_limit", "external_reference_id", "created_at", "voice_in_trunks" ] } }, "example": [ "id", "name" ] }, "VoiceOutTrunkFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "allow_any_did_as_cli": { "type": "boolean", "description": "Matches trunks by whether any DID the account owns is accepted as the caller ID." }, "authentication_method.type": { "type": "string", "description": "Matches trunks authenticated in this way. Accepts a comma-separated list, matching any of the values." }, "default_did.id": { "type": "string", "description": "Matches trunks whose default caller ID is this DID. A DID the account does not own is rejected rather than matching nothing." }, "default_dst_action": { "type": "string", "description": "Matches trunks by what they do with destinations not listed in `dst_prefixes`.", "enum": [ "allow_all", "reject_all" ] }, "external_reference_id": { "type": "string", "description": "Matches trunks whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the trunk by its identifier. Accepts a comma-separated list, matching any of the values." }, "media_encryption_mode": { "type": "string", "description": "Matches trunks requiring this media encryption.", "enum": [ "disabled", "srtp_sdes", "srtp_dtls", "zrtp" ] }, "name": { "type": "string", "description": "Matches trunks whose name is exactly this value." }, "name_contains": { "type": "string", "description": "Matches trunks whose name contains this value." }, "on_cli_mismatch_action": { "type": "string", "description": "Matches trunks with this action for a caller ID that is not allowed. An action the account does not have the feature for is rejected.", "enum": [ "reject_call", "replace_cli", "send_original_cli", "randomize_cli" ] }, "status": { "type": "string", "description": "Matches trunks by whether the account has blocked them from placing calls.", "enum": [ "active", "blocked" ] }, "threshold_reached": { "type": "boolean", "description": "Matches trunks by whether spending has passed `threshold_amount`." } } } }, "VoiceOutTrunkSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "allow_any_did_as_cli", "-allow_any_did_as_cli", "created_at", "-created_at", "external_reference_id", "-external_reference_id", "name", "-name", "threshold_reached", "-threshold_reached" ] } }, "example": [ "allow_any_did_as_cli" ] }, "VoiceOutTrunkPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, "VoiceOutTrunkFields": { "name": "fields[voice_out_trunks]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "status", "external_reference_id", "capacity_limit", "allow_any_did_as_cli", "on_cli_mismatch_action", "default_dst_action", "dst_prefixes", "media_encryption_mode", "allowed_rtp_ips", "force_symmetric_rtp", "rtp_ping", "rtp_timeout", "threshold_amount", "callback_url", "emergency_enable_all", "created_at", "threshold_reached", "authentication_method", "dids", "emergency_dids" ] } }, "example": [ "id", "name" ] }, "IdentityFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "birth_date": { "type": "string", "description": "Matches identities with this date of birth." }, "company_name": { "type": "string", "description": "Matches identities whose company name is exactly this value." }, "company_name_contains": { "type": "string", "description": "Matches identities whose company name contains this value." }, "company_reg_number": { "type": "string", "description": "Matches identities whose company registration number is exactly this value." }, "company_reg_number_contains": { "type": "string", "description": "Matches identities whose company registration number contains this value." }, "country.id": { "type": "string", "description": "Matches identities registered in the country. Accepts a comma-separated list, matching any of the values." }, "description": { "type": "string", "description": "Matches identities whose description is exactly this value." }, "description_contains": { "type": "string", "description": "Matches identities whose description contains this value." }, "external_reference_id": { "type": "string", "description": "Matches identities whose external reference identifier is exactly this value." }, "first_name": { "type": "string", "description": "Matches identities whose first name is exactly this value." }, "first_name_contains": { "type": "string", "description": "Matches identities whose first name contains this value." }, "id": { "type": "string", "description": "Matches the identity by its identifier. Accepts a comma-separated list, matching any of the values." }, "id_number": { "type": "string", "description": "Matches identities whose identification document number is exactly this value." }, "id_number_contains": { "type": "string", "description": "Matches identities whose identification document number contains this value." }, "identity_type": { "type": "string", "description": "Matches identities registered to a person or to a company.", "enum": [ "personal", "business" ] }, "last_name": { "type": "string", "description": "Matches identities whose last name is exactly this value." }, "last_name_contains": { "type": "string", "description": "Matches identities whose last name contains this value." }, "personal_tax_id": { "type": "string", "description": "Matches identities whose personal tax identifier is exactly this value." }, "personal_tax_id_contains": { "type": "string", "description": "Matches identities whose personal tax identifier contains this value." }, "phone_number": { "type": "string", "description": "Matches identities whose contact number is exactly this value." }, "phone_number_contains": { "type": "string", "description": "Matches identities whose contact number contains this value." }, "vat_id": { "type": "string", "description": "Matches identities whose VAT identification number is exactly this value." }, "vat_id_contains": { "type": "string", "description": "Matches identities whose VAT identification number contains this value." } } } }, "IdentitySort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "birth_date", "-birth_date", "company_name", "-company_name", "company_reg_number", "-company_reg_number", "contact_email", "-contact_email", "created_at", "-created_at", "description", "-description", "external_reference_id", "-external_reference_id", "first_name", "-first_name", "id_number", "-id_number", "last_name", "-last_name", "personal_tax_id", "-personal_tax_id", "phone_number", "-phone_number", "vat_id", "-vat_id", "verified", "-verified" ] } }, "example": [ "birth_date" ] }, "IdentityPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "IdentityFields": { "name": "fields[identities]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "identity_type", "first_name", "last_name", "phone_number", "contact_email", "company_name", "company_reg_number", "vat_id", "id_number", "personal_tax_id", "birth_date", "description", "external_reference_id", "created_at", "verified", "country", "birth_country", "proofs", "addresses", "permanent_documents" ] } }, "example": [ "id", "identity_type" ] }, "AddressFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "Matches addresses whose street address is exactly this value." }, "address_contains": { "type": "string", "description": "Matches addresses whose street address contains this value." }, "area.id": { "type": "string", "description": "Matches addresses located in the regulatory area. Accepts a comma-separated list, matching any of the values." }, "city.id": { "type": "string", "description": "Matches addresses located in the city. Accepts a comma-separated list, matching any of the values." }, "city_name": { "type": "string", "description": "Matches addresses whose city name is exactly this value." }, "city_name_contains": { "type": "string", "description": "Matches addresses whose city name contains this value." }, "country.id": { "type": "string", "description": "Matches addresses located in the country. Accepts a comma-separated list, matching any of the values." }, "description": { "type": "string", "description": "Matches addresses whose description is exactly this value." }, "description_contains": { "type": "string", "description": "Matches addresses whose description contains this value." }, "external_reference_id": { "type": "string", "description": "Matches addresses whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the address by its identifier. Accepts a comma-separated list, matching any of the values." }, "identity.external_reference_id": { "type": "string", "description": "Matches addresses whose identity has exactly this external reference identifier." }, "identity.id": { "type": "string", "description": "Matches addresses belonging to the identity. Accepts a comma-separated list, matching any of the values." }, "postal_code": { "type": "string", "description": "Matches addresses whose postal code is exactly this value." }, "postal_code_contains": { "type": "string", "description": "Matches addresses whose postal code contains this value." } } } }, "AddressSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "-address", "city_name", "-city_name", "created_at", "-created_at", "description", "-description", "external_reference_id", "-external_reference_id", "postal_code", "-postal_code", "verified", "-verified" ] } }, "example": [ "address" ] }, "AddressPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "AddressFields": { "name": "fields[addresses]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "address", "city_name", "postal_code", "description", "external_reference_id", "created_at", "verified", "identity", "country", "area", "city", "proofs" ] } }, "example": [ "id", "address" ] }, "ProofTypeFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "description": "Matches proof types proving this kind of entity. Accepts a comma-separated list, matching any of the values. Accepted values: `Address`, `Business`, `Personal`." }, "id": { "type": "string", "description": "Matches the proof type by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "ProofTypeFields": { "name": "fields[proof_types]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "entity_type" ] } }, "example": [ "id", "name" ] }, "ProofFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Matches proofs whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the proof by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "ProofSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "expires_at", "-expires_at", "external_reference_id", "-external_reference_id" ] } }, "example": [ "created_at" ] }, "ProofPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ProofFields": { "name": "fields[proofs]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "created_at", "expires_at", "external_reference_id", "proof_type", "entity" ] } }, "example": [ "id", "created_at" ] }, "SupportingDocumentTemplateFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Matches the supporting document template by its identifier. Accepts a comma-separated list, matching any of the values." }, "name": { "type": "string", "description": "Matches templates whose name is exactly this value. Accepts a comma-separated list, matching any of the values." }, "name_contains": { "type": "string", "description": "Matches templates whose name contains this value." }, "permanent": { "type": "boolean", "description": "Matches templates whose completed form stays on file rather than being submitted per address verification." } } } }, "SupportingDocumentTemplateSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "name", "-name", "permanent", "-permanent" ] } }, "example": [ "name" ] }, "SupportingDocumentTemplatePageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "SupportingDocumentTemplateFields": { "name": "fields[supporting_document_templates]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "permanent", "url" ] } }, "example": [ "id", "name" ] }, "PermanentSupportingDocumentFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "external_reference_id": { "type": "string", "description": "Matches documents whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the permanent supporting document by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "PermanentSupportingDocumentSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "external_reference_id", "-external_reference_id" ] } }, "example": [ "created_at" ] }, "PermanentSupportingDocumentPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "PermanentSupportingDocumentFields": { "name": "fields[permanent_supporting_documents]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "created_at", "external_reference_id", "template", "identity" ] } }, "example": [ "id", "created_at" ] }, "EncryptedFileFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Matches the encrypted file by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "EncryptedFileSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "description", "-description", "expire_at", "-expire_at", "expires_at", "-expires_at" ] } }, "example": [ "description" ] }, "EncryptedFilePageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "EncryptedFileFields": { "name": "fields[encrypted_files]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "description", "expires_at" ] } }, "example": [ "id", "description" ] }, "AddressRequirementFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches address requirements of the country. Accepts a comma-separated list, matching any of the values." }, "did_group_type.id": { "type": "string", "description": "Matches address requirements of the DID group type. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the address requirement by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "AddressRequirementSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address_proof_qty", "-address_proof_qty", "business_proof_qty", "-business_proof_qty", "personal_proof_qty", "-personal_proof_qty", "restriction_message", "-restriction_message", "service_description_required", "-service_description_required" ] } }, "example": [ "address_proof_qty" ] }, "AddressRequirementPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "AddressRequirementFields": { "name": "fields[address_requirements]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "identity_type", "personal_area_level", "business_area_level", "address_area_level", "personal_proof_qty", "business_proof_qty", "address_proof_qty", "personal_mandatory_fields", "business_mandatory_fields", "service_description_required", "restriction_message", "country", "did_group_type", "personal_permanent_document", "business_permanent_document", "personal_onetime_document", "business_onetime_document", "personal_proof_types", "business_proof_types", "address_proof_types" ] } }, "example": [ "id", "identity_type" ] }, "AddressVerificationFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "address.id": { "type": "string", "description": "Matches verifications submitted for the address. Accepts a comma-separated list, matching any of the values." }, "address.identity.id": { "type": "string", "description": "Matches verifications whose address belongs to the identity. Accepts a comma-separated list, matching any of the values." }, "external_reference_id": { "type": "string", "description": "Matches verifications whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the verification by its identifier. Accepts a comma-separated list, matching any of the values." }, "reference": { "type": "string", "description": "Matches verifications whose reference contains this value." }, "reference_in": { "type": "string", "description": "Matches verifications whose reference is exactly one of these values. Accepts a comma-separated list, matching any of the values." }, "status": { "type": "string", "description": "Matches verifications in this review state.", "enum": [ "pending", "approved", "rejected" ] } } } }, "AddressVerificationSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "external_reference_id", "-external_reference_id" ] } }, "example": [ "created_at" ] }, "AddressVerificationPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "AddressVerificationFields": { "name": "fields[address_verifications]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "reference", "status", "reject_reasons", "reject_comment", "service_description", "callback_url", "callback_method", "external_reference_id", "created_at", "address", "dids" ] } }, "example": [ "id", "reference" ] }, "EmergencyRequirementFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "country.id": { "type": "string", "description": "Matches requirements that apply in the country. Accepts a comma-separated list, matching any of the values." }, "did_group_type.id": { "type": "string", "description": "Matches requirements that apply to numbers of the DID group type. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the emergency requirement by its identifier. Accepts a comma-separated list, matching any of the values." } } } }, "EmergencyRequirementPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "EmergencyRequirementFields": { "name": "fields[emergency_requirements]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "identity_type", "personal_area_level", "business_area_level", "address_area_level", "personal_mandatory_fields", "business_mandatory_fields", "address_mandatory_fields", "estimate_setup_time", "requirement_restriction_message", "country", "did_group_type" ] } }, "example": [ "id", "identity_type" ] }, "EmergencyCallingServiceFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "address.id": { "type": "string", "description": "Matches subscriptions whose latest verification registered this address." }, "country.id": { "type": "string", "description": "Matches subscriptions for numbers in the country. Accepts a comma-separated list, matching any of the values." }, "did_group_type.id": { "type": "string", "description": "Matches subscriptions for numbers of the DID group type. Accepts a comma-separated list, matching any of the values." }, "id": { "type": "string", "description": "Matches the subscription by its identifier. Accepts a comma-separated list, matching any of the values." }, "identity.id": { "type": "string", "description": "Matches subscriptions whose latest verification registered an address belonging to the identity." }, "name": { "type": "string", "description": "Matches subscriptions whose name contains this value." }, "reference": { "type": "string", "description": "Matches the subscription with exactly this reference." }, "status": { "type": "string", "description": "Matches subscriptions in this lifecycle state.", "enum": [ "active", "canceled", "new", "changes_required", "in_process", "pending_update" ] } } } }, "EmergencyCallingServiceSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country.name", "-country.name", "created_at", "-created_at", "name", "-name", "renew_date", "-renew_date", "status", "-status" ] } }, "example": [ "country.name" ] }, "EmergencyCallingServicePageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "EmergencyCallingServiceFields": { "name": "fields[emergency_calling_services]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "name", "reference", "status", "activated_at", "canceled_at", "renew_date", "created_at", "country", "did_group_type", "order", "emergency_requirement", "emergency_verification", "dids" ] } }, "example": [ "id", "name" ] }, "EmergencyVerificationFilter": { "name": "filter", "in": "query", "required": false, "style": "deepObject", "explode": true, "description": "Filters, sent as `filter[]=`.", "schema": { "type": "object", "properties": { "emergency_calling_service.id": { "type": "string", "description": "Matches verifications submitted for the emergency calling service. Accepts a comma-separated list, matching any of the values." }, "external_reference_id": { "type": "string", "description": "Matches verifications whose external reference identifier is exactly this value." }, "id": { "type": "string", "description": "Matches the verification by its identifier. Accepts a comma-separated list, matching any of the values." }, "status": { "type": "string", "description": "Matches verifications in this review state.", "enum": [ "approved", "pending", "rejected" ] } } } }, "EmergencyVerificationSort": { "name": "sort", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sort fields, applied in order. Prefix a field with `-` to sort descending.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "created_at", "-created_at", "external_reference_id", "-external_reference_id" ] } }, "example": [ "created_at" ] }, "EmergencyVerificationPageSize": { "name": "page[size]", "in": "query", "required": false, "description": "Records per page. The maximum can be raised for an individual account, so a key may be allowed more than this.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "EmergencyVerificationFields": { "name": "fields[emergency_verifications]", "in": "query", "required": false, "style": "form", "explode": false, "description": "Sparse fieldset. When sent, `attributes` and `relationships` are pruned to the listed fields. The response schemas in this document describe the full, unpruned set.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "reference", "status", "reject_reasons", "reject_comment", "callback_url", "callback_method", "external_reference_id", "created_at", "address", "emergency_calling_service", "dids" ] } }, "example": [ "id", "reference" ] } } }, "security": [ { "api_key": [] } ], "paths": { "/balance": { "get": { "summary": "Read the balance", "tags": [ "Account" ], "operationId": "getBalance", "description": "Returns the authenticated customer's balance. This is a singleton resource: the path is singular and takes no id.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/BalanceFields" } ], "responses": { "200": { "description": "balance returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/BalanceDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_history": { "get": { "summary": "List DID history", "tags": [ "Account" ], "operationId": "listDidHistory", "description": "Returns what happened to the customer's numbers — when each was assigned, renewed, cancelled or removed, and through which interface. Retained for 90 days; a `created_at_gteq` or `created_at_lteq` before that window is rejected.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidHistoryFilter" }, { "$ref": "#/components/parameters/DidHistorySort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/DidHistoryPageSize" }, { "$ref": "#/components/parameters/DidHistoryFields" } ], "responses": { "200": { "description": "history returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidHistoryCollectionDocument" } } } }, "400": { "description": "malformed request — a date outside the retention window", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_history/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "History entry identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a DID history entry", "tags": [ "Account" ], "operationId": "getDidHistoryEntry", "description": "One entry of the ownership history, by its identifier. Entries age out of the API on the same window the collection describes, so an identifier that answered yesterday can answer 404 today.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidHistoryFields" } ], "responses": { "200": { "description": "history entry returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidHistoryDocument" } } } }, "404": { "description": "no history entry with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/exports": { "post": { "summary": "Request a CDR export", "tags": [ "Account" ], "operationId": "createExport", "description": "Queues a CDR export. The file is generated asynchronously: poll the export until `status` is `completed`, then fetch `url`. `filters.from` and `filters.to` must both fall within the current or the two preceding months.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "exportReady": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The export finished (POST)", "description": "Sent once the file has been generated and can be downloaded. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "id", "type", "status", "url" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The export this is about." }, "type": { "type": "string", "enum": [ "exports" ], "description": "Always `exports`." }, "status": { "type": "string", "description": "The state the export settled in." }, "url": { "type": "string", "format": "uri", "description": "Where to download the file." } } } } } } }, "get": { "summary": "The export finished (GET)", "description": "Sent once the file has been generated and can be downloaded. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment — with the payload appended to that query, sorted by name and URL-encoded, before the fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The export this is about." }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "exports" ] }, "description": "Always `exports`." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The state the export settled in." }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Where to download the file." } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } } } } } }, "responses": { "201": { "description": "export queued", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportDocument" } } } }, "422": { "description": "the date range was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportCreateRequest" } } }, "required": true } }, "get": { "summary": "List exports", "tags": [ "Account" ], "operationId": "listExports", "description": "Returns the exports this account has requested. An export stays `pending` until its file has been generated and carries no `url` until then; supply a `callback_url` on creation to be told when it is ready instead of polling.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/ExportFilter" }, { "$ref": "#/components/parameters/ExportSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/ExportPageSize" }, { "$ref": "#/components/parameters/ExportFields" } ], "responses": { "200": { "description": "exports returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/exports/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Export identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an export", "tags": [ "Account" ], "operationId": "getExport", "description": "Returns a single export. `url` is null until `status` is `completed`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/ExportFields" } ], "responses": { "200": { "description": "export returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportDocument" } } } }, "404": { "description": "no export with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an export", "tags": [ "Account" ], "operationId": "updateExport", "description": "Changes the customer's own reference on an export.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "export updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportDocument" } } } }, "404": { "description": "no export with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ExportUpdateRequest" } } }, "required": true } } }, "/exports/{filename}.csv.gz": { "get": { "summary": "Download an export", "tags": [ "Account" ], "operationId": "downloadExport", "description": "Downloads the generated file of a completed export. Do not build this path by hand: a completed export reports the whole URL in its `url` attribute, and the segment below is the file name inside it — not the export id. The response is the gzipped CSV itself rather than a JSONAPI document; a pending export has no `url` and nothing to download.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "filename", "in": "path", "required": true, "description": "The `filename` of a completed export.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "the export file", "content": { "application/gzip": { "schema": { "type": "string", "format": "binary", "description": "The gzipped CSV." } } } }, "404": { "description": "no completed export of the customer has that filename" }, "401": { "description": "missing or invalid api-key" } } } }, "/address_verifications": { "get": { "summary": "List address verifications", "tags": [ "Address verifications" ], "operationId": "listAddressVerifications", "description": "Returns the address verifications the customer has submitted. `status` is `pending` until DIDWW has reviewed one; a `rejected` verification explains itself in `reject_reasons` and `reject_comment`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/AddressVerificationFilter" }, { "$ref": "#/components/parameters/AddressVerificationSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/AddressVerificationPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "dids" ] } }, "example": [ "address" ] }, { "$ref": "#/components/parameters/AddressVerificationFields" } ], "responses": { "200": { "description": "address verifications returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Submit an address verification", "tags": [ "Address verifications" ], "operationId": "createAddressVerification", "description": "Submits an address for approval against the DIDs listed in `dids`. Whatever the matching address requirement demands must already be in place: the identity's permanent supporting documents, its proofs, and — where the requirement asks for them — one-time documents supplied here as `onetime_files`. Check a candidate first with POST /address_requirement_validations.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "addressVerificationReviewed": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The address verification was reviewed (POST)", "description": "Sent once DIDWW has approved or rejected the submission. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "id", "type", "status", "reject_reason", "reject_comment" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The verification this is about." }, "type": { "type": "string", "enum": [ "address_verifications" ], "description": "Always `address_verifications`." }, "status": { "type": "string", "description": "The outcome: `approved` or `rejected`." }, "reject_reason": { "type": "string", "description": "Why it was rejected, as one line — several reasons are joined with `, `. Empty when it was approved." }, "reject_comment": { "type": "string", "description": "Free-form note from the reviewer, if any." } } } } } } }, "get": { "summary": "The address verification was reviewed (GET)", "description": "Sent once DIDWW has approved or rejected the submission. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment — with the payload appended to that query, sorted by name and URL-encoded, before the fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The verification this is about." }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "address_verifications" ] }, "description": "Always `address_verifications`." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The outcome: `approved` or `rejected`." }, { "name": "reject_reason", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Why it was rejected, as one line — several reasons are joined with `, `. Empty when it was approved." }, { "name": "reject_comment", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Free-form note from the reviewer, if any." } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } } } } } }, "responses": { "201": { "description": "address verification submitted", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationDocument" } } } }, "422": { "description": "the submission was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationCreateRequest" } } }, "required": true } } }, "/address_verifications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Address verification identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an address verification", "tags": [ "Address verifications" ], "operationId": "getAddressVerification", "description": "One verification, by its identifier. `status` stays `pending` until DIDWW has reviewed the submission out of band; a rejected one explains itself in `reject_reasons` and `reject_comment`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "dids" ] } }, "example": [ "address" ] }, { "$ref": "#/components/parameters/AddressVerificationFields" } ], "responses": { "200": { "description": "address verification returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationDocument" } } } }, "404": { "description": "no address verification with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an address verification", "tags": [ "Address verifications" ], "operationId": "updateAddressVerification", "description": "Changes the customer's own reference. A rejected verification is replaced by submitting a new one, not by editing this one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "address verification updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationDocument" } } } }, "404": { "description": "no address verification with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressVerificationUpdateRequest" } } }, "required": true } } }, "/capacity_pools": { "get": { "summary": "List capacity pools", "tags": [ "Capacity" ], "operationId": "listCapacityPools", "description": "Returns the capacity pools available to the customer, with how many channels it owns (`total_channels_count`), how many are in use (`assigned_channels_count`) and what more cost — see the `qty_based_pricings` relationship for the volume breaks.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/CapacityPoolFilter" }, { "$ref": "#/components/parameters/CapacityPoolSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/CapacityPoolPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "countries", "shared_capacity_groups", "qty_based_pricings" ] } }, "example": [ "countries" ] }, { "$ref": "#/components/parameters/CapacityPoolFields" } ], "responses": { "200": { "description": "capacity pools returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CapacityPoolCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/capacity_pools/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Capacity pool identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a capacity pool", "tags": [ "Capacity" ], "operationId": "getCapacityPool", "description": "One capacity pool, by its identifier. `assigned_channels_count` against `total_channels_count` is what says how much of the pool is already carrying numbers.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "countries", "shared_capacity_groups", "qty_based_pricings" ] } }, "example": [ "countries" ] }, { "$ref": "#/components/parameters/CapacityPoolFields" } ], "responses": { "200": { "description": "capacity pool returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CapacityPoolDocument" } } } }, "404": { "description": "no capacity pool with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Release channels from a capacity pool", "tags": [ "Capacity" ], "operationId": "updateCapacityPool", "description": "Lowers `total_channels_count`, releasing channels. Channels are bought with a `capacity_order_items` order, never by raising this number — an increase is rejected.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "channels released", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CapacityPoolDocument" } } } }, "422": { "description": "the new channel count was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no capacity pool with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CapacityPoolUpdateRequest" } } }, "required": true } } }, "/shared_capacity_groups": { "get": { "summary": "List shared capacity groups", "tags": [ "Capacity" ], "operationId": "listSharedCapacityGroups", "description": "Returns the groups that let several numbers draw on the same channels of a capacity pool. Filter on `capacity_pool.id` for the groups of one pool.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/SharedCapacityGroupFilter" }, { "$ref": "#/components/parameters/SharedCapacityGroupSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/SharedCapacityGroupPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "capacity_pool", "dids" ] } }, "example": [ "capacity_pool" ] }, { "$ref": "#/components/parameters/SharedCapacityGroupFields" } ], "responses": { "200": { "description": "shared capacity groups returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create a shared capacity group", "tags": [ "Capacity" ], "operationId": "createSharedCapacityGroup", "description": "Creates a group of DIDs sharing channels from a capacity pool. `shared_channels_count` cannot exceed the pool's unassigned channels.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "shared capacity group created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupDocument" } } } }, "422": { "description": "the group was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupCreateRequest" } } }, "required": true } } }, "/shared_capacity_groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Shared capacity group identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a shared capacity group", "tags": [ "Capacity" ], "operationId": "getSharedCapacityGroup", "description": "One shared capacity group, by its identifier. `include=dids` lists the numbers sharing its channels.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "capacity_pool", "dids" ] } }, "example": [ "capacity_pool" ] }, { "$ref": "#/components/parameters/SharedCapacityGroupFields" } ], "responses": { "200": { "description": "shared capacity group returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupDocument" } } } }, "404": { "description": "no shared capacity group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update a shared capacity group", "tags": [ "Capacity" ], "operationId": "updateSharedCapacityGroup", "description": "Updates a group. Sending `dids` replaces the whole set of DIDs sharing the channels.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "shared capacity group updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupDocument" } } } }, "404": { "description": "no shared capacity group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SharedCapacityGroupUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete a shared capacity group", "tags": [ "Capacity" ], "operationId": "deleteSharedCapacityGroup", "description": "Deletes the group and returns its channels to the pool.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "shared capacity group deleted" }, "404": { "description": "no shared capacity group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/countries": { "get": { "summary": "List countries", "tags": [ "Coverage" ], "operationId": "listCountries", "description": "Returns every country DIDWW has, or may have, coverage in. The whole list is returned in one response — this endpoint is not paginated.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/CountryFilter" }, { "$ref": "#/components/parameters/CountrySort" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regions" ] } }, "example": [ "regions" ] }, { "$ref": "#/components/parameters/CountryFields" } ], "responses": { "200": { "description": "countries returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CountryCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/countries/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Country identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a country", "tags": [ "Coverage" ], "operationId": "getCountry", "description": "One country, by its identifier. Its regions, cities and areas are read from /regions, /cities and /areas filtered on `country.id`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "regions" ] } }, "example": [ "regions" ] }, { "$ref": "#/components/parameters/CountryFields" } ], "responses": { "200": { "description": "country returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CountryDocument" } } } }, "404": { "description": "no country with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/regions": { "get": { "summary": "List regions", "tags": [ "Coverage" ], "operationId": "listRegions", "description": "Returns the regions of the countries whose coverage is organised by region. Not paginated.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/RegionFilter" }, { "$ref": "#/components/parameters/RegionSort" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/RegionFields" } ], "responses": { "200": { "description": "regions returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RegionCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/regions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Region identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a region", "tags": [ "Coverage" ], "operationId": "getRegion", "description": "One region, by its identifier — the administrative division between a country and its cities. Not every country has them.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/RegionFields" } ], "responses": { "200": { "description": "region returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/RegionDocument" } } } }, "404": { "description": "no region with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/cities": { "get": { "summary": "List cities", "tags": [ "Coverage" ], "operationId": "listCities", "description": "Returns the cities DIDWW sells numbers in. Narrow it with `country.id`, `region.id` or `area.id`, and with `is_available` to drop the ones where nothing can be bought right now.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/CityFilter" }, { "$ref": "#/components/parameters/CitySort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/CityPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "region", "area" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/CityFields" } ], "responses": { "200": { "description": "cities returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CityCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/cities/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "City identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a city", "tags": [ "Coverage" ], "operationId": "getCity", "description": "One city, by its identifier. A city belongs to a country and, where the country has them, to a region and an area.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "region", "area" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/CityFields" } ], "responses": { "200": { "description": "city returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/CityDocument" } } } }, "404": { "description": "no city with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/areas": { "get": { "summary": "List areas", "tags": [ "Coverage" ], "operationId": "listAreas", "description": "Returns the regulatory areas within countries. An address requirement can demand that a registered address sit in the same area as the number.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/AreaFilter" }, { "$ref": "#/components/parameters/AreaSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/AreaPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/AreaFields" } ], "responses": { "200": { "description": "areas returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AreaCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/areas/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Area identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an area", "tags": [ "Coverage" ], "operationId": "getArea", "description": "One area, by its identifier — the coverage unit a regulated address is matched against when a requirement demands a local one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/AreaFields" } ], "responses": { "200": { "description": "area returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AreaDocument" } } } }, "404": { "description": "no area with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_group_types": { "get": { "summary": "List DID group types", "tags": [ "Coverage" ], "operationId": "listDidGroupTypes", "description": "Returns the kinds of number DIDWW offers — Local, Mobile, Toll-free and so on.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidGroupTypeFilter" }, { "$ref": "#/components/parameters/DidGroupTypeSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/DidGroupTypePageSize" }, { "$ref": "#/components/parameters/DidGroupTypeFields" } ], "responses": { "200": { "description": "DID group types returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidGroupTypeCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_group_types/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DID group type identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a DID group type", "tags": [ "Coverage" ], "operationId": "getDidGroupType", "description": "One DID group type, by its identifier: what kind of number a group offers — local, national, mobile, toll-free.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidGroupTypeFields" } ], "responses": { "200": { "description": "DID group type returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidGroupTypeDocument" } } } }, "404": { "description": "no DID group type with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/public_keys": { "get": { "summary": "List public keys", "tags": [ "Regulation" ], "operationId": "listPublicKeys", "description": "Returns the RSA public keys to encrypt regulation documents with before uploading them to /encrypted_files. Either key may be used. This is the one collection in the API that carries neither `meta` nor `links`.", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/PublicKeyFilter" }, { "$ref": "#/components/parameters/PublicKeyFields" } ], "responses": { "200": { "description": "public keys returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PublicKeyCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_groups": { "get": { "summary": "List DID groups", "tags": [ "DID groups" ], "operationId": "listDidGroups", "description": "Returns the coverage catalogue: which blocks of numbers exist, what they support and — through `stock_keeping_units` — what they cost. `meta.total_count` on each group is how many numbers are in stock, and `meta.needs_registration` whether buying one requires a verified address.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidGroupFilter" }, { "$ref": "#/components/parameters/DidGroupSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/DidGroupPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "city", "did_group_type", "region", "stock_keeping_units", "address_requirement" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/DidGroupFields" } ], "responses": { "200": { "description": "DID groups returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidGroupCollectionDocument" } } } }, "400": { "description": "malformed request — unknown feature, filter or sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DID group identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a DID group", "tags": [ "DID groups" ], "operationId": "getDidGroup", "description": "One DID group, by its identifier. The group carries the price and the capabilities; the individual numbers in it are read from /available_dids when `available_dids_enabled` is true.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "city", "did_group_type", "region", "stock_keeping_units", "address_requirement" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/DidGroupFields" } ], "responses": { "200": { "description": "DID group returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidGroupDocument" } } } }, "404": { "description": "no DID group with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/available_dids": { "get": { "summary": "List available DIDs", "tags": [ "DID groups" ], "operationId": "listAvailableDids", "description": "Returns individual numbers in stock, for the DID groups whose `meta.available_dids_enabled` is true. Not paginated: the result set is capped and `meta.total_count` reports how many numbers matched. Reserve one with POST /did_reservations, or buy it directly with an `available_did_id` order item.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/AvailableDidFilter" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "did_group", "nanpa_prefix" ] } }, "example": [ "did_group" ] }, { "$ref": "#/components/parameters/AvailableDidFields" } ], "responses": { "200": { "description": "available DIDs returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AvailableDidCollectionDocument" } } } }, "400": { "description": "malformed request — `number_contains` needs at least 3 digits or a coverage filter", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/available_dids/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Available DID identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an available DID", "tags": [ "DID groups" ], "operationId": "getAvailableDid", "description": "One number on offer, by its identifier. Availability is not a promise: a number listed now can be gone by the time an order reaches it, which is what /did_reservations is for.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "did_group", "nanpa_prefix" ] } }, "example": [ "did_group" ] }, { "$ref": "#/components/parameters/AvailableDidFields" } ], "responses": { "200": { "description": "available DID returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AvailableDidDocument" } } } }, "404": { "description": "no available DID with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_reservations": { "post": { "summary": "Reserve an available DID", "tags": [ "DID reservations" ], "operationId": "createDidReservation", "description": "Holds an available DID so nobody else can take it before the order is placed. The hold lapses at `expires_at`. The number of reservations a customer may hold at once is capped by its plan.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "DID reserved", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidReservationCreatedDocument" } } } }, "422": { "description": "the DID cannot be reserved", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidReservationCreateRequest" } } }, "required": true } }, "get": { "summary": "List reservations", "tags": [ "DID reservations" ], "operationId": "listDidReservations", "description": "Returns the reservations the customer currently holds. `meta.available_count` is how many more it may take.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidReservationFilter" }, { "$ref": "#/components/parameters/DidReservationSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/DidReservationPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "available_did" ] } }, "example": [ "available_did" ] }, { "$ref": "#/components/parameters/DidReservationFields" } ], "responses": { "200": { "description": "reservations returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidReservationCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/did_reservations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reservation identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a reservation", "tags": [ "DID reservations" ], "operationId": "getDidReservation", "description": "One reservation, by its identifier. `expires_at` is when the hold lapses and the number goes back on offer.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "available_did" ] } }, "example": [ "available_did" ] }, { "$ref": "#/components/parameters/DidReservationFields" } ], "responses": { "200": { "description": "reservation returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidReservationDocument" } } } }, "404": { "description": "no reservation with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "delete": { "summary": "Release a reservation", "tags": [ "DID reservations" ], "operationId": "deleteDidReservation", "description": "Releases the hold and returns the number to the pool.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "reservation released" }, "404": { "description": "no reservation with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/dids": { "get": { "summary": "List DIDs", "tags": [ "DIDs" ], "operationId": "listDids", "description": "Returns the DIDs the customer owns, ordered by number unless `sort` says otherwise.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/DidFilter" }, { "$ref": "#/components/parameters/DidSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/DidPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "did_group", "order", "capacity_pool", "shared_capacity_group", "address_verification", "voice_in_trunk", "voice_in_trunk_group", "emergency_calling_service", "emergency_verification", "identity" ] } }, "example": [ "did_group" ] }, { "$ref": "#/components/parameters/DidFields" } ], "responses": { "200": { "description": "DIDs returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/dids/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "DID identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a DID", "tags": [ "DIDs" ], "operationId": "getDid", "description": "Returns a single DID.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "did_group", "order", "capacity_pool", "shared_capacity_group", "address_verification", "voice_in_trunk", "voice_in_trunk_group", "emergency_calling_service", "emergency_verification", "identity" ] } }, "example": [ "did_group" ] }, { "$ref": "#/components/parameters/DidFields" } ], "responses": { "200": { "description": "DID returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidDocument" } } } }, "404": { "description": "no DID with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update a DID", "tags": [ "DIDs" ], "operationId": "updateDid", "description": "Updates the writable fields of a DID: its note, capacity, routing and billing cycles. Setting `terminated` to `true` cancels the DID.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "DID updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidDocument" } } } }, "422": { "description": "the update was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no DID with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/DidUpdateRequest" } } }, "required": true } } }, "/emergency_requirements": { "get": { "summary": "List emergency requirements", "tags": [ "Emergency" ], "operationId": "listEmergencyRequirements", "description": "Returns what each country demands before emergency calling can be activated, and what it costs for this account — `meta.setup_price` and `meta.monthly_price`. A country and group type this account has no emergency rate for is not returned.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/EmergencyRequirementFilter" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/EmergencyRequirementPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/EmergencyRequirementFields" } ], "responses": { "200": { "description": "emergency requirements returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyRequirementCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter or bad pagination", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/emergency_requirements/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Emergency requirement identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an emergency requirement", "tags": [ "Emergency" ], "operationId": "getEmergencyRequirement", "description": "One emergency requirement, by its identifier: what a country demands before emergency calling can be activated on a number of a given group type.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/EmergencyRequirementFields" } ], "responses": { "200": { "description": "emergency requirement returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyRequirementDocument" } } } }, "404": { "description": "no emergency requirement with that id is priced for this account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/emergency_requirement_validations": { "post": { "summary": "Check an identity or address against an emergency requirement", "tags": [ "Emergency" ], "operationId": "createEmergencyRequirementValidation", "description": "Dry run, exactly like POST /address_requirement_validations but against an emergency requirement: 201 with an empty resource when it is satisfied, 422 naming what is missing otherwise. Nothing is stored.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "the requirement is satisfied", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyRequirementValidationDocument" } } } }, "422": { "description": "the requirement is not satisfied", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyRequirementValidationCreateRequest" } } }, "required": true } } }, "/emergency_calling_services": { "get": { "summary": "List emergency calling services", "tags": [ "Emergency" ], "operationId": "listEmergencyCallingServices", "description": "Returns the emergency calling subscriptions the customer has. There is no POST here: a subscription is created by placing an order with an `emergency_order_items` entry.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/EmergencyCallingServiceFilter" }, { "$ref": "#/components/parameters/EmergencyCallingServiceSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/EmergencyCallingServicePageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type", "order", "emergency_requirement", "emergency_verification", "dids" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/EmergencyCallingServiceFields" } ], "responses": { "200": { "description": "emergency calling services returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyCallingServiceCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/emergency_calling_services/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Emergency calling service identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an emergency calling service", "tags": [ "Emergency" ], "operationId": "getEmergencyCallingService", "description": "One emergency calling service, by its identifier — the subscription that carries emergency calling for a set of numbers, and the address those calls are dispatched to.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type", "order", "emergency_requirement", "emergency_verification", "dids" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/EmergencyCallingServiceFields" } ], "responses": { "200": { "description": "emergency calling service returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyCallingServiceDocument" } } } }, "404": { "description": "no emergency calling service with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "delete": { "summary": "Cancel an emergency calling service", "tags": [ "Emergency" ], "operationId": "deleteEmergencyCallingService", "description": "Cancels the subscription. `status` becomes `canceled`, `canceled_at` is set and `renew_date` goes null.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "emergency calling service cancelled" }, "404": { "description": "no emergency calling service with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/emergency_verifications": { "get": { "summary": "List emergency verifications", "tags": [ "Emergency" ], "operationId": "listEmergencyVerifications", "description": "Returns the emergency verifications this account has submitted. `status` stays `pending` until DIDWW has reviewed one; a rejected one explains itself in `reject_reasons` and `reject_comment`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/EmergencyVerificationFilter" }, { "$ref": "#/components/parameters/EmergencyVerificationSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/EmergencyVerificationPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "emergency_calling_service", "dids" ] } }, "example": [ "address" ] }, { "$ref": "#/components/parameters/EmergencyVerificationFields" } ], "responses": { "200": { "description": "emergency verifications returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Submit an emergency verification", "tags": [ "Emergency" ], "operationId": "createEmergencyVerification", "description": "Activates emergency calling. Two modes: send `dids` and no `emergency_calling_service` to activate the numbers, which creates the calling service as well; send `emergency_calling_service` and no `dids` to register a different address against a subscription that already exists. DIDWW reviews the submission out of band, so `status` starts at `pending`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "emergencyVerificationReviewed": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The emergency verification was reviewed (POST)", "description": "Sent once DIDWW has approved or rejected the submission. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "id", "type", "status", "reject_reasons", "reject_comment", "emergency_calling_service_id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The verification this is about." }, "type": { "type": "string", "enum": [ "emergency_verifications" ], "description": "Always `emergency_verifications`." }, "status": { "type": "string", "description": "The outcome: `approved` or `rejected`." }, "reject_reasons": { "type": "string", "description": "Why it was rejected — several reasons are joined with `; `. Empty when it was approved." }, "reject_comment": { "type": "string", "description": "Free-form note from the reviewer, if any." }, "emergency_calling_service_id": { "type": "string", "format": "uuid", "description": "The subscription the verification belongs to." } } } } } } }, "get": { "summary": "The emergency verification was reviewed (GET)", "description": "Sent once DIDWW has approved or rejected the submission. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment — with the payload appended to that query, sorted by name and URL-encoded, before the fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The verification this is about." }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "emergency_verifications" ] }, "description": "Always `emergency_verifications`." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The outcome: `approved` or `rejected`." }, { "name": "reject_reasons", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Why it was rejected — several reasons are joined with `; `. Empty when it was approved." }, { "name": "reject_comment", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Free-form note from the reviewer, if any." }, { "name": "emergency_calling_service_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The subscription the verification belongs to." } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } } } } } }, "responses": { "201": { "description": "emergency verification submitted, creating the calling service", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationDocument" } } } }, "422": { "description": "the submission was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationCreateRequest" } } }, "required": true } } }, "/emergency_verifications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Emergency verification identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an emergency verification", "tags": [ "Emergency" ], "operationId": "getEmergencyVerification", "description": "One emergency verification, by its identifier. It is the submission, not the subscription: the service it created or re-verified is `emergency_calling_service`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "address", "emergency_calling_service", "dids" ] } }, "example": [ "address" ] }, { "$ref": "#/components/parameters/EmergencyVerificationFields" } ], "responses": { "200": { "description": "emergency verification returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationDocument" } } } }, "404": { "description": "no emergency verification with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an emergency verification", "tags": [ "Emergency" ], "operationId": "updateEmergencyVerification", "description": "Changes the customer's own reference. A rejected verification is replaced by submitting a new one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "emergency verification updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationDocument" } } } }, "404": { "description": "no emergency verification with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "emergency calling is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EmergencyVerificationUpdateRequest" } } }, "required": true } } }, "/nanpa_prefixes": { "get": { "summary": "List NANPA prefixes", "tags": [ "DID groups" ], "operationId": "listNanpaPrefixes", "description": "Returns the NPA-NXX prefixes DIDWW has numbers behind. Filter by `npanxx` to find a specific rate centre, then pass the prefix id as `nanpa_prefix_id` on a `did_order_items` order to restrict the numbers bought to it.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/NanpaPrefixFilter" }, { "$ref": "#/components/parameters/NanpaPrefixSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/NanpaPrefixPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "region" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/NanpaPrefixFields" } ], "responses": { "200": { "description": "NANPA prefixes returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/NanpaPrefixCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/nanpa_prefixes/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "NANPA prefix identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a NANPA prefix", "tags": [ "DID groups" ], "operationId": "getNanpaPrefix", "description": "One NANPA prefix, by its identifier. A prefix pins an order to one rate centre inside a North American DID group.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "region" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/NanpaPrefixFields" } ], "responses": { "200": { "description": "NANPA prefix returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/NanpaPrefixDocument" } } } }, "404": { "description": "no NANPA prefix with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/orders": { "post": { "summary": "Place an order", "tags": [ "Orders" ], "operationId": "createOrder", "description": "Places an order. An order is a list of items; a `did_order_items` entry buys numbers from a stock keeping unit, a `capacity_order_items` entry buys channels for a capacity pool. The order is charged against the customer balance immediately and may complete asynchronously — poll it until `status` leaves `pending`, or supply `callback_url`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "orderSettled": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The order reached its final state (POST)", "description": "Sent once the order stops being `pending` — filled, or canceled because something in it could not be filled. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "id", "type", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The order this is about." }, "type": { "type": "string", "enum": [ "orders" ], "description": "Always `orders`." }, "status": { "type": "string", "description": "The state the order settled in: `completed` or `canceled`." } } } } } } }, "get": { "summary": "The order reached its final state (GET)", "description": "Sent once the order stops being `pending` — filled, or canceled because something in it could not be filled. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment — with the payload appended to that query, sorted by name and URL-encoded, before the fragment, then the payload members sorted by name, with name and value concatenated. Every value is already a string on the wire, a null being the empty one. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The order this is about." }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "orders" ] }, "description": "Always `orders`." }, { "name": "status", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The state the order settled in: `completed` or `canceled`." } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } } } } } }, "responses": { "201": { "description": "order placed", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderDocument" } } } }, "400": { "description": "the body is malformed — required item data missing or not allowed, or a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the customer is in read-only mode", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the order was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderCreateRequest" } } }, "required": true } }, "get": { "summary": "List orders", "tags": [ "Orders" ], "operationId": "listOrders", "description": "Returns the orders the customer has placed.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/OrderFilter" }, { "$ref": "#/components/parameters/OrderSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/OrderPageSize" }, { "$ref": "#/components/parameters/OrderFields" } ], "responses": { "200": { "description": "orders returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/orders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an order", "tags": [ "Orders" ], "operationId": "getOrder", "description": "Returns a single order. Poll it until `status` leaves `pending` to find out whether the numbers were provisioned.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/OrderFields" } ], "responses": { "200": { "description": "order returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderDocument" } } } }, "404": { "description": "no order with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an order", "tags": [ "Orders" ], "operationId": "updateOrder", "description": "Changes the customer's own reference on a placed order. Nothing else about an order can be changed.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "order updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderDocument" } } } }, "404": { "description": "no order with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/OrderUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Cancel an order", "tags": [ "Orders" ], "operationId": "deleteOrder", "description": "Cancels a DID order. Only DID orders can be cancelled, and only while no balance hold is required for them — anything else answers 422.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "order cancelled" }, "422": { "description": "the order cannot be cancelled", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no order with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/identities": { "get": { "summary": "List identities", "tags": [ "Regulation" ], "operationId": "listIdentities", "description": "Returns the identities the customer has registered. `verified` counts DIDs rather than paperwork — it turns true once the identity is registered to at least one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/IdentityFilter" }, { "$ref": "#/components/parameters/IdentitySort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/IdentityPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "birth_country", "proofs", "addresses", "permanent_documents" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/IdentityFields" } ], "responses": { "200": { "description": "identities returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create an identity", "tags": [ "Regulation" ], "operationId": "createIdentity", "description": "Creates an identity. Which of the optional attributes are actually mandatory is decided per country by the matching address requirement — see `personal_mandatory_fields` / `business_mandatory_fields` on /address_requirements, and check a candidate with POST /address_requirement_validations.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "identity created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityDocument" } } } }, "422": { "description": "the identity was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityCreateRequest" } } }, "required": true } } }, "/identities/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identity identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an identity", "tags": [ "Regulation" ], "operationId": "getIdentity", "description": "One identity, by its identifier. An identity is what regulated numbers are registered against; `verified` says whether any are registered against this one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "birth_country", "proofs", "addresses", "permanent_documents" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/IdentityFields" } ], "responses": { "200": { "description": "identity returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityDocument" } } } }, "404": { "description": "no identity with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an identity", "tags": [ "Regulation" ], "operationId": "updateIdentity", "description": "Updates an identity. `identity_type` cannot change: switching between personal and business would invalidate the documents already on file.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "identity updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityDocument" } } } }, "404": { "description": "no identity with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/IdentityUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete an identity", "tags": [ "Regulation" ], "operationId": "deleteIdentity", "description": "Deletes an identity along with its addresses and documents.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "identity deleted" }, "409": { "description": "the identity is still in use: it is the account identity of an account that is still open, a DID number names it as its main or its porting identity, an emergency calling service registered to it has not finished, or an SMS campaign registered to it has not finished", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no identity with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/addresses": { "get": { "summary": "List addresses", "tags": [ "Regulation" ], "operationId": "listAddresses", "description": "Returns the customer's registered addresses. `verified` counts DIDs rather than paperwork — it turns true once the address is registered to at least one; filter on `identity.id` for the addresses of one identity.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/AddressFilter" }, { "$ref": "#/components/parameters/AddressSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/AddressPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "identity", "country", "area", "city", "proofs" ] } }, "example": [ "identity" ] }, { "$ref": "#/components/parameters/AddressFields" } ], "responses": { "200": { "description": "addresses returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create an address", "tags": [ "Regulation" ], "operationId": "createAddress", "description": "Creates an address for an identity. Submit it for approval with POST /address_verifications.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "address created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressDocument" } } } }, "422": { "description": "the address was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressCreateRequest" } } }, "required": true } } }, "/addresses/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Address identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an address", "tags": [ "Regulation" ], "operationId": "getAddress", "description": "One address, by its identifier. The documents behind it are its `proofs`; whether DIDWW has accepted them is the `status` of an /address_verifications record, not `verified`, which counts the DIDs registered to the address.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "identity", "country", "area", "city", "proofs" ] } }, "example": [ "identity" ] }, { "$ref": "#/components/parameters/AddressFields" } ], "responses": { "200": { "description": "address returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressDocument" } } } }, "404": { "description": "no address with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an address", "tags": [ "Regulation" ], "operationId": "updateAddress", "description": "Updates an address. Neither `identity` nor `country` can change — reassigning a verified address would invalidate the verification.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "address updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressDocument" } } } }, "404": { "description": "no address with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete an address", "tags": [ "Regulation" ], "operationId": "deleteAddress", "description": "Removes the address from the account. It is kept on file rather than erased where regulation requires it — an address behind an approved verification stays referenced by what it registered, and stops appearing in reads.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "address deleted" }, "409": { "description": "the address is still in use: it is the billing address of an account that is still open, a verification of it is still new or pending, an emergency calling service registered to it has not finished, or an SMS campaign registered to it has not finished", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no address with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/encrypted_files": { "post": { "summary": "Upload an encrypted file", "tags": [ "Regulation" ], "operationId": "createEncryptedFile", "description": "Stages a regulation document. This is the one endpoint in the V3 API that is not JSONAPI: it takes a `multipart/form-data` upload. Encrypt the file with one of the /public_keys first and pass the fingerprint of the key pair as `encrypted_files[encryption_fingerprint]` — the two fingerprints joined by `:::`. The body it answers with is an ordinary JSONAPI document, sent as `application/json` rather than `application/vnd.api+json`; reference the id it returns when creating a proof, a permanent supporting document or an address verification.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EncryptedFileUploadRequest" } } } }, "responses": { "201": { "description": "encrypted file staged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptedFileDocument" } } } }, "422": { "description": "the upload was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the request parameters are invalid — the body was not a multipart upload, or it carried a field the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "get": { "summary": "List encrypted files", "tags": [ "Regulation" ], "operationId": "listEncryptedFiles", "description": "Returns the files staged for use as regulation documents. A staged file is deleted at `expires_at` unless it has been attached to something by then.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/EncryptedFileFilter" }, { "$ref": "#/components/parameters/EncryptedFileSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/EncryptedFilePageSize" }, { "$ref": "#/components/parameters/EncryptedFileFields" } ], "responses": { "200": { "description": "encrypted files returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EncryptedFileCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/encrypted_files/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Encrypted file identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an encrypted file", "tags": [ "Regulation" ], "operationId": "getEncryptedFile", "description": "One staged file, by its identifier. The file itself is never returned: this reports that it is still staged and when it expires if nothing references it.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/EncryptedFileFields" } ], "responses": { "200": { "description": "encrypted file returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/EncryptedFileDocument" } } } }, "404": { "description": "no encrypted file with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "delete": { "summary": "Delete an encrypted file", "tags": [ "Regulation" ], "operationId": "deleteEncryptedFile", "description": "Deletes a staged file before it expires.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "encrypted file deleted" }, "404": { "description": "no encrypted file with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/proofs": { "get": { "summary": "List proofs", "tags": [ "Regulation" ], "operationId": "listProofs", "description": "Returns the documents attached to identities and addresses as evidence. The files themselves are never returned by a read.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/ProofFilter" }, { "$ref": "#/components/parameters/ProofSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/ProofPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "proof_type", "entity" ] } }, "example": [ "proof_type" ] }, { "$ref": "#/components/parameters/ProofFields" } ], "responses": { "200": { "description": "proofs returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create a proof", "tags": [ "Regulation" ], "operationId": "createProof", "description": "Attaches a document to an identity or an address as evidence. Upload the file to /encrypted_files first and reference it here — the files are copied onto the proof and are not returned by any read. `entity.type` must be `identities` or `addresses`, matching what the `proof_type` proves.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "proof created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofDocument" } } } }, "422": { "description": "the proof was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofCreateRequest" } } }, "required": true } } }, "/proofs/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proof identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a proof", "tags": [ "Regulation" ], "operationId": "getProof", "description": "One proof, by its identifier. `entity` is what it proves — an identity or an address — and `expires_at` is when the document stops being accepted.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "proof_type", "entity" ] } }, "example": [ "proof_type" ] }, { "$ref": "#/components/parameters/ProofFields" } ], "responses": { "200": { "description": "proof returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofDocument" } } } }, "404": { "description": "no proof with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update a proof", "tags": [ "Regulation" ], "operationId": "updateProof", "description": "Changes the customer's own reference on a proof. Replace the document by deleting the proof and creating a new one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "proof updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofDocument" } } } }, "404": { "description": "no proof with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete a proof", "tags": [ "Regulation" ], "operationId": "deleteProof", "description": "Removes the proof. A proof cannot be removed while an address verification that relies on it is still under review; delete it after the review or replace the document by creating a new proof.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "proof deleted" }, "422": { "description": "the proof is relied on by a verification still under review", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no proof with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/supporting_document_templates": { "get": { "summary": "List supporting document templates", "tags": [ "Regulation" ], "operationId": "listSupportingDocumentTemplates", "description": "Returns the blank forms an address requirement can demand. Download `url`, fill it in, and submit it either as a permanent supporting document or with an address verification, depending on `permanent`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/SupportingDocumentTemplateFilter" }, { "$ref": "#/components/parameters/SupportingDocumentTemplateSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/SupportingDocumentTemplatePageSize" }, { "$ref": "#/components/parameters/SupportingDocumentTemplateFields" } ], "responses": { "200": { "description": "templates returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentTemplateCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/supporting_document_templates/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Supporting document template identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a supporting document template", "tags": [ "Regulation" ], "operationId": "getSupportingDocumentTemplate", "description": "One template, by its identifier: the blank form a country demands, to be completed and uploaded. `permanent` says whether the completed form stays on file or is submitted per address verification.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/SupportingDocumentTemplateFields" } ], "responses": { "200": { "description": "template returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/SupportingDocumentTemplateDocument" } } } }, "404": { "description": "no supporting document template with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/permanent_supporting_documents": { "get": { "summary": "List permanent supporting documents", "tags": [ "Regulation" ], "operationId": "listPermanentSupportingDocuments", "description": "Returns the completed forms held on file against identities. Filter on `external_reference_id` to find one by the identifier the customer gave it.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/PermanentSupportingDocumentFilter" }, { "$ref": "#/components/parameters/PermanentSupportingDocumentSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PermanentSupportingDocumentPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "template", "identity" ] } }, "example": [ "template" ] }, { "$ref": "#/components/parameters/PermanentSupportingDocumentFields" } ], "responses": { "200": { "description": "documents returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create a permanent supporting document", "tags": [ "Regulation" ], "operationId": "createPermanentSupportingDocument", "description": "Puts a completed template on file against an identity, so it does not have to be resubmitted with every address verification. A new document supersedes and removes the one the identity already has for the same template.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "document created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentDocument" } } } }, "422": { "description": "the document was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentCreateRequest" } } }, "required": true } } }, "/permanent_supporting_documents/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Permanent supporting document identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a permanent supporting document", "tags": [ "Regulation" ], "operationId": "getPermanentSupportingDocument", "description": "One permanent supporting document, by its identifier. The files behind it are never returned by a read; `template` is the blank form it completes.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "template", "identity" ] } }, "example": [ "template" ] }, { "$ref": "#/components/parameters/PermanentSupportingDocumentFields" } ], "responses": { "200": { "description": "document returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentDocument" } } } }, "404": { "description": "no permanent supporting document with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update a permanent supporting document", "tags": [ "Regulation" ], "operationId": "updatePermanentSupportingDocument", "description": "Changes the customer's own reference on a document. Replace the content by creating a new document for the same identity and template; it supersedes the previous one.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "document updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentDocument" } } } }, "404": { "description": "no permanent supporting document with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PermanentSupportingDocumentUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete a permanent supporting document", "tags": [ "Regulation" ], "operationId": "deletePermanentSupportingDocument", "description": "Removes the document from the identity. It cannot be removed while an address verification that relies on it is still under review.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "document deleted" }, "422": { "description": "the document is relied on by a verification still under review", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no permanent supporting document with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/proof_types": { "get": { "summary": "List proof types", "tags": [ "Regulation" ], "operationId": "listProofTypes", "description": "Returns the kinds of document accepted as a proof, and what each proves. Not paginated.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/ProofTypeFilter" }, { "$ref": "#/components/parameters/ProofTypeFields" } ], "responses": { "200": { "description": "proof types returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofTypeCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/proof_types/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Proof type identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read a proof type", "tags": [ "Regulation" ], "operationId": "getProofType", "description": "One proof type, by its identifier: a kind of document DIDWW accepts, and which of an identity or an address it proves.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/ProofTypeFields" } ], "responses": { "200": { "description": "proof type returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ProofTypeDocument" } } } }, "404": { "description": "no proof type with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/address_requirements": { "get": { "summary": "List address requirements", "tags": [ "Regulation" ], "operationId": "listAddressRequirements", "description": "Returns what each country demands before a number from a given group type can be registered: which identity types it accepts, how close the address must be, how many proofs, and which forms.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/AddressRequirementFilter" }, { "$ref": "#/components/parameters/AddressRequirementSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/AddressRequirementPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type", "personal_permanent_document", "business_permanent_document", "personal_onetime_document", "business_onetime_document", "personal_proof_types", "business_proof_types", "address_proof_types" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/AddressRequirementFields" } ], "responses": { "200": { "description": "address requirements returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressRequirementCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/address_requirements/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Address requirement identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an address requirement", "tags": [ "Regulation" ], "operationId": "getAddressRequirement", "description": "One address requirement, by its identifier: what a country demands before a number of a given group type can be registered — which fields, how many proofs, and how local the address has to be.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "did_group_type", "personal_permanent_document", "business_permanent_document", "personal_onetime_document", "business_onetime_document", "personal_proof_types", "business_proof_types", "address_proof_types" ] } }, "example": [ "country" ] }, { "$ref": "#/components/parameters/AddressRequirementFields" } ], "responses": { "200": { "description": "address requirement returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressRequirementDocument" } } } }, "404": { "description": "no address requirement with that id", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/address_requirement_validations": { "post": { "summary": "Check an identity or address against an address requirement", "tags": [ "Regulation" ], "operationId": "createAddressRequirementValidation", "description": "Dry run: answers 201 with an empty resource when the identity and/or address satisfies the requirement, and 422 naming what is missing otherwise. Nothing is stored. At least one of `identity` and `address` must be sent.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "the requirement is satisfied", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressRequirementValidationDocument" } } } }, "422": { "description": "the requirement is not satisfied", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/AddressRequirementValidationCreateRequest" } } }, "required": true } } }, "/voice_in_trunks": { "get": { "summary": "List inbound trunks", "tags": [ "Inbound trunks" ], "operationId": "listVoiceInTrunks", "description": "Returns the inbound voice trunks the customer has configured.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/VoiceInTrunkFilter" }, { "$ref": "#/components/parameters/VoiceInTrunkSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/VoiceInTrunkPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "voice_in_trunk_group", "pop" ] } }, "example": [ "voice_in_trunk_group" ] }, { "$ref": "#/components/parameters/VoiceInTrunkFields" } ], "responses": { "200": { "description": "trunks returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create an inbound trunk", "tags": [ "Inbound trunks" ], "operationId": "createVoiceInTrunk", "description": "Creates an inbound voice trunk. `configuration` is required and its `type` decides which attributes it takes.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "trunk created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkDocument" } } } }, "422": { "description": "the trunk was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body is malformed — `configuration` missing, or a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkCreateRequest" } } }, "required": true } } }, "/voice_in_trunks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trunk identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an inbound trunk", "tags": [ "Inbound trunks" ], "operationId": "getVoiceInTrunk", "description": "One inbound trunk, by its identifier. `configuration` carries the transport-specific settings, and its shape is determined by `configuration.type`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "voice_in_trunk_group", "pop" ] } }, "example": [ "voice_in_trunk_group" ] }, { "$ref": "#/components/parameters/VoiceInTrunkFields" } ], "responses": { "200": { "description": "trunk returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkDocument" } } } }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an inbound trunk", "tags": [ "Inbound trunks" ], "operationId": "updateVoiceInTrunk", "description": "Updates a trunk. `configuration` is written member by member: what you send is applied, what you omit keeps its stored value, and `type` must match the trunk's own.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "trunk updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkDocument" } } } }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete an inbound trunk", "tags": [ "Inbound trunks" ], "operationId": "deleteVoiceInTrunk", "description": "Deletes a trunk. Rejected with 422 while any DID is routed to it, or while it belongs to a trunk group — route those DIDs elsewhere and leave the group first.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "trunk deleted" }, "422": { "description": "the trunk is still in use", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/voice_in_trunk_groups": { "get": { "summary": "List inbound trunk groups", "tags": [ "Inbound trunks" ], "operationId": "listVoiceInTrunkGroups", "description": "Returns the groups that spread inbound calls over several trunks. A DID is routed either to a trunk or to a group, never to both.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/VoiceInTrunkGroupFilter" }, { "$ref": "#/components/parameters/VoiceInTrunkGroupSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/VoiceInTrunkGroupPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "voice_in_trunks" ] } }, "example": [ "voice_in_trunks" ] }, { "$ref": "#/components/parameters/VoiceInTrunkGroupFields" } ], "responses": { "200": { "description": "trunk groups returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create an inbound trunk group", "tags": [ "Inbound trunks" ], "operationId": "createVoiceInTrunkGroup", "description": "Creates a trunk group. Listing `voice_in_trunks` moves those trunks into it.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "trunk group created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupDocument" } } } }, "422": { "description": "the trunk group was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupCreateRequest" } } }, "required": true } } }, "/voice_in_trunk_groups/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Inbound trunk group identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an inbound trunk group", "tags": [ "Inbound trunks" ], "operationId": "getVoiceInTrunkGroup", "description": "One trunk group, by its identifier. `include=voice_in_trunks` lists its members, whose `priority` and `weight` decide how calls are spread over them.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "voice_in_trunks" ] } }, "example": [ "voice_in_trunks" ] }, { "$ref": "#/components/parameters/VoiceInTrunkGroupFields" } ], "responses": { "200": { "description": "trunk group returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupDocument" } } } }, "404": { "description": "no trunk group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an inbound trunk group", "tags": [ "Inbound trunks" ], "operationId": "updateVoiceInTrunkGroup", "description": "Updates a trunk group. Sending `voice_in_trunks` replaces its whole membership.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "200": { "description": "trunk group updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupDocument" } } } }, "404": { "description": "no trunk group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceInTrunkGroupUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete an inbound trunk group", "tags": [ "Inbound trunks" ], "operationId": "deleteVoiceInTrunkGroup", "description": "Deletes a trunk group and the trunks in it — a member trunk is not kept as a standalone trunk. Refused while the group, or any trunk in it, is routed to a DID; route those DIDs elsewhere first.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "trunk group deleted" }, "404": { "description": "no trunk group with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/pops": { "get": { "summary": "List points of presence", "tags": [ "Inbound trunks" ], "operationId": "listPops", "description": "Returns the points of presence an inbound trunk can be pinned to. Not paginated, and not sortable.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/PopFilter" }, { "$ref": "#/components/parameters/PopFields" } ], "responses": { "200": { "description": "points of presence returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PopCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/voice_out_trunks": { "get": { "summary": "List outbound trunks", "tags": [ "Outbound trunks" ], "operationId": "listVoiceOutTrunks", "description": "Returns the outbound voice trunks the customer has configured. Each trunk reports what it has spent this period in `meta.spent_amount`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "$ref": "#/components/parameters/VoiceOutTrunkFilter" }, { "$ref": "#/components/parameters/VoiceOutTrunkSort" }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/VoiceOutTrunkPageSize" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "dids", "emergency_dids" ] } }, "example": [ "dids" ] }, { "$ref": "#/components/parameters/VoiceOutTrunkFields" } ], "responses": { "200": { "description": "trunks returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkCollectionDocument" } } } }, "400": { "description": "malformed request — unknown filter, bad pagination or bad sort field", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "post": { "summary": "Create an outbound trunk", "tags": [ "Outbound trunks" ], "operationId": "createVoiceOutTrunk", "description": "Creates an outbound trunk. `authentication_method` is required and its `type` decides how calls are authenticated; `credentials_and_ip` returns generated SIP credentials in the response.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "voiceOutTrunkBlockingChanged": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The trunk was blocked or unblocked (POST)", "description": "Sent when the trunk starts or stops being blocked — by the spending threshold, or by hand. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then, for each entry in order, its members sorted by name with name and value concatenated. A value is concatenated as JSON writes it, so the boolean is `true` or `false` in lower case — not as the language you parsed it into would print it. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "One entry per event. Events that pile up while a delivery is failing are sent together in the next attempt.", "items": { "type": "object", "required": [ "id", "type", "status", "threshold_reached", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The trunk this is about." }, "type": { "type": "string", "enum": [ "voice_out_trunks" ], "description": "Always `voice_out_trunks`." }, "status": { "type": "string", "description": "The trunk state after the event: `blocked` or `active`." }, "threshold_reached": { "type": "boolean", "description": "Whether the spending threshold was what blocked it." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event happened." } } } } } } } } } } }, "responses": { "201": { "description": "trunk created", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkDocument" } } } }, "422": { "description": "the trunk was rejected", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkCreateRequest" } } }, "required": true } } }, "/voice_out_trunks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Outbound trunk identifier.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Read an outbound trunk", "tags": [ "Outbound trunks" ], "operationId": "getVoiceOutTrunk", "description": "One outbound trunk, by its identifier. `authentication_method` carries the credentials or the address allowlist, and its shape is determined by `authentication_method.type`.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "include", "in": "query", "required": false, "style": "form", "explode": false, "description": "Relationships to return in the top-level `included` array. A value may be extended with dotted segments (`a.b`), each of which must be a relationship of the resource named before it; the values listed here are the first segment.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "dids", "emergency_dids" ] } }, "example": [ "dids" ] }, { "$ref": "#/components/parameters/VoiceOutTrunkFields" } ], "responses": { "200": { "description": "trunk returned", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkDocument" } } } }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } }, "patch": { "summary": "Update an outbound trunk", "tags": [ "Outbound trunks" ], "operationId": "updateVoiceOutTrunk", "description": "Updates an outbound trunk. Set `status` to `blocked` to stop it placing calls. Assigning `dids` is rejected while `allow_any_did_as_cli` is true.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "callbacks": { "voiceOutTrunkBlockingChanged": { "{$request.body#/data/attributes/callback_url}": { "post": { "summary": "The trunk was blocked or unblocked (POST)", "description": "Sent when the trunk starts or stops being blocked — by the spending threshold, or by hand. Delivered only while the account has an API key with callbacks enabled; without one nothing is sent and nothing is retried.", "parameters": [ { "name": "X-DIDWW-Signature", "in": "header", "required": true, "description": "SHA1 HMAC in lowercase hexadecimal, keyed with an API key of the account that has callbacks enabled, over the callback URL normalised — scheme (defaulting to `http`), userinfo where the URL carries it, host, the port always explicit, path, the URL's own query, and finally its fragment, then, for each entry in order, its members sorted by name with name and value concatenated. A value is concatenated as JSON writes it, so the boolean is `true` or `false` in lower case — not as the language you parsed it into would print it. Verify it before acting on the request.", "schema": { "type": "string", "pattern": "^[0-9a-f]{40}$", "example": "0123456789abcdef0123456789abcdef01234567" } } ], "responses": { "2XX": { "description": "A status from 200 to 298 is taken as delivered and the event is not sent again." }, "4XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." }, "5XX": { "description": "Treated as a failed delivery — as is a timeout, which is 60 seconds. Delivered 10 times in all — the first attempt and 9 retries at a widening interval — after which the event is dropped." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "One entry per event. Events that pile up while a delivery is failing are sent together in the next attempt.", "items": { "type": "object", "required": [ "id", "type", "status", "threshold_reached", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The trunk this is about." }, "type": { "type": "string", "enum": [ "voice_out_trunks" ], "description": "Always `voice_out_trunks`." }, "status": { "type": "string", "description": "The trunk state after the event: `blocked` or `active`." }, "threshold_reached": { "type": "boolean", "description": "Whether the spending threshold was what blocked it." }, "created_at": { "type": "string", "format": "date-time", "description": "When the event happened." } } } } } } } } } } }, "responses": { "200": { "description": "trunk updated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkDocument" } } } }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "422": { "description": "the external reference is longer than the API accepts", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkUpdateRequest" } } }, "required": true } }, "delete": { "summary": "Delete an outbound trunk", "tags": [ "Outbound trunks" ], "operationId": "deleteVoiceOutTrunk", "description": "Removes the outbound trunk. Calls placed through it stop immediately, and the numbers it allowed as caller ID are released — they are not deleted with it.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "204": { "description": "trunk deleted" }, "404": { "description": "no trunk with that id belongs to the customer", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } } } }, "/voice_out_trunk_regenerate_credentials": { "post": { "summary": "Regenerate outbound trunk credentials", "tags": [ "Outbound trunks" ], "operationId": "createVoiceOutTrunkRegenerateCredential", "description": "Rotates the SIP credentials of a `credentials_and_ip` trunk. The response carries nothing but the identifier — read the new credentials back from the trunk.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "responses": { "201": { "description": "credentials regenerated", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkRegenerateCredentialDocument" } } } }, "422": { "description": "the trunk has no credentials to rotate", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "400": { "description": "the body carries a member the API does not accept", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "403": { "description": "the outbound voice API is not enabled for the account", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "406": { "description": "the requested media type cannot be served", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "415": { "description": "the request body was sent under an unsupported media type", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } }, "401": { "description": "missing or invalid api-key", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorsDocument" } } } } }, "requestBody": { "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/VoiceOutTrunkRegenerateCredentialCreateRequest" } } }, "required": true } } } } }