Provisioning API Specification

This document defines a RESTful, JSON-based, HTTPS Provisioning Enablement API for a telecommunications provider or service. The API is designed to be a single, normalized Cloud API layer over internal provider systems used for communications service provisioning.

The specification is designed for generic communications service provisioning, certain workflows however require specifics. Zilkr’s largest production deployment is an enablement for phone number provisioning, thus phone number provisioning is often specified. A reader may replace phone numbers with their specific service (e.g. UCaaS seats) when considering the Zilkr Provisioning Enablement API service.

Key concepts

Common to any provisioning system, the following key concepts exist in the API:

• A Customer is an account in a provisioning system that searches for and orders products, and pays for the resulting service.
• A Product is what a customer wants to order service on and pay for. E.g. toll-free phone numbers, a UCaaS seat, etc.
• An Order is the set of information a customer provides so that it may acquire a new service, or manage an existing service.

For example, imagine Acme, Inc needs to buy 10 toll-free phone numbers in the United States. Acme, Inc is the customer. Toll-free phone numbers is the product. The process by which Acme, Inc buys 10 numbers is an order.

This API executes either in the Zilkr AWS cloud or a private datacenter, with custom integrations built into each provisioning subsystem. Zilkr customizes this API for each deployment, operates an API sandbox service, and either Zilkr or a systems integrator takes responsibility for provisioning systems integrations.

Glossary

API Resources:

• Customers are accounts in the system that search for, order and pay for product services.
  • Contacts are contact details of people in a Customer account.
  • Payment Methods are the different ways a Customer pays for an order.
  • Locations are physical addresses of Customer sites or locations where service is delivered.
  • Inventory are the Customer’s active services.
  • Invoices are bills that a Customer must pay.
• Products define types of products being provisioned and geographies where they may be available.
  • Numbers are phone number specific products such as toll-free, local, etc.
  • Reservations are when (applicable) product quantities are reserved for later ordering.
• Orders allow placement of New service requests, or MACD (Move, Add, Change, Delete) requests on existing service.

API Actions:

• Creation of resources, defined by a POST HTTP method.
• Retrieval of a list or specific resource, defined by a GET HTTP method.
• Management of existing resources, defined by PUT and DELETE HTTP methods.

Specification

Customers

Make & manage customer accounts.

• GET /customers Get all your customer entities

  Returns 200 OK

• POST /customers Create a new customer account

  Returns 201 Created

• GET /customers/{customerId} Get a specific customer

  Returns 200 OK

• PUT /customers/{customerId} Update a specific customer

  Returns 200 OK

• DELETE /customers/{customerId} Remove a specific customer

  Returns 204 No Content

Contacts

Make & manage contacts belonging to a customer. A sub-resource to Customer.

• GET /customers/{customerId}/contacts Get all your contacts

  Returns 200 OK

• POST /customers/{customerId}/contacts Create a new contact for a customer

  Returns 201 Created

• GET /customers/{customerId}/contacts/{contactId} Get a specific contact

  Returns 200 OK

• PUT /customers/{customerId}/contacts/{contactId} Update a specific contact

  Returns 200 OK

• DELETE /customers/{customerId}/contacts/{contactId} Remove a specific contact

  Returns 204 No Content

Payment Methods

Make & manage payment profiles for a customer. A sub-resource to Customer.

• GET /customers/{customerId}/paymentMethods Get all your payment methods

  Returns 200 OK

• POST /customers/{customerId}/paymentMethods Create a new payment method for a customer

  Returns 201 Created

• GET /customers/{customerId}/paymentMethods/{paymentMethodId} Get a specific payment method

  Returns 200 OK

• PUT /customers/{customerId}/paymentMethods/{paymentMethodId} Update a specific payment method

  Returns 200 OK

Locations

Make & manage sites or locations belonging to a customer. A sub-resource to Customer.

• GET /customers/{customerId}/productLocations Get all your product locations

  Returns 200 OK

• POST /customers/{customerId}/productLocations Create a new product location for a customer

  Returns 201 Created

• GET /customers/{customerId}/productLocations/{locationId} Get a specific product location

  Returns 200 OK

• PUT /customers/{customerId}/productLocations/{locationId} Update a specific product location

  Returns 200 OK

• DELETE /customers/{customerId}/productLocations/{locationId} Remove a specific product location

  Returns 204 No Content

Inventory

Search active product inventory of a customer. A sub-resource to Customer.

• GET /customers/{customerId}/connections Get all active connections, e.g. SIP trunks, IP circuits, etc.

  Returns 200 OK

• GET /customers/{customerId}/connections/{connectionId} Get a specific active connection

  Returns 200 OK

• GET /customers/{customerId}/products Get all your in-service products

  Returns 200 OK

• GET /customers/{customerId}/products/{productId} Get a specific in-service product

  Returns 200 OK

Invoices

See active service invoices for a Customer. A sub-resource to Customer.

• GET /customers/{customerId}/invoices Get all your invoices for completed orders

  Returns 200 OK

• GET /customers/{customerId}/invoices/{invoiceId} Get a specific active connection

  Returns 200 OK

Products and Countries

Search a product catalog across countries & cities.

• GET /products Get the products catalog

  Returns 200 OK

• GET /products/{productId} Get details on a specific product in the catalog

  Returns 200 OK

• GET /countries Get a list of countries where products are offered

  Returns 200 OK

• GET /countries/{countryCode} Gets one specific country where products are offered

  Returns 200 OK

• GET /countries/{countryCode}/cities Get a list of cities for a country where one/more products are offered

  Returns 200 OK

• GET /countries/{countryCode}/cities/{cityId} Gets one specific city where products are offered

  Returns 200 OK

Orders

Make product orders, for setting up new service or managing in-place services. Requires a valid Customer account.

When this API enables Products that are not phone numbers, these command URLs will change.

• POST /customers/{customerId}/orders/{productId}/numbers/any Order product with any available phone numbers

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/port Order product with phone numbers to port

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/reserve Order product with reserved phone numbers

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/range Order product with phone number ranges

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/move Order to move number locations

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/change Order to change the characteristics of numbers

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/numbers/delete Order to delete numbers from a customer inventory

  Returns 201 Created

• POST /customers/{customerId}/orders/{productId}/delete Order to delete every number of this product from a customer inventory

  Returns 201 Created

• GET /customers/{customerId}/orders Get all your orders

  Returns 200 OK

• DELETE /customers/{customerId}/orders/{orderId} Get a specific order

  Returns 200 OK

• GET /customers/{customerId}/orders/{orderId} Cancel a specific order

  Returns 204 No Content

Number availability and Reservations

When Products are phone numbers (toll-free, local, etc), search for and reserve products.

When this API enables other products, these commands may not be applicable.

• GET /numbers Search for available numbers across number products and countries

  Returns 200 OK

• GET /customers/{customerId}/reservations Get all your number reservations

  Returns 200 OK

• POST /customers/{customerId}/reservations Create a new number reservation for a customer

  Returns 201 Created

• GET /customers/{customerId}/reservations/{reservationId} Get a specific number reservation

  Returns 200 OK

• DELETE /customers/{customerId}/reservations/{reservationId} Remove a specific number reservation

  Returns 204 No Content

Swagger

Get the .json Swagger specification of this API here.

Next steps

Automating a communications provisioning service is hugely expensive to create from the ground up. Zilkr’s Provisioning Enablement service greatly reduces time-to-market, as well as providing best practice API expertise in the design, build and operate phases.

The nature of this service requires it to be customized for each provider, please don’t hesitate to ask us any questions.

Send a message