openapi: '3.1.0' info: title: Porting API description: Automated processing of port-in phone number operations version: '1.0' license: name: MIT url: "https://www.sinch.com/toc" servers: - url: https://porting.api.sinch.com/v1/projects/{projectId} description: v1.0 of the porting API variables: projectId: description: The project with which you are working. default: YOUR_project_id tags: - name: Port-in numbers description: |- You can create orders, check portability, and more. When you port in phone numbers to Sinch you need to make sure the numbers are portable, you can use the portability check to make sure the numbers are portable before creating an order. If a number is not portable the whole order will fail. When porting a number to Sinch you can either use the dashboard or the API, the API is recommended for larger orders and for automation. **Note:** For port orders of over 500 numbers, please contact the [support team](https://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1572). The recommended way to port numbers to Sinch is to schedule the port, this means that you create an order and specify a desired port date and time, If you have more advanced needs like on-demand activation, you can read more about that in the [advanced porting section](/tag/Advanced-porting/). ### Porting orders In general you work with porting orders, a porting order is the resource that keeps the number(s) status and progress in one place. Before creating port order you should check the portability of the numbers you want to port in, if a number is not portable the order will fail. ```json POST /portabilityChecks { "phoneNumbers": ["+12345678901"] } ``` If the number is portable you can create an order like this: ```json POST v1/projects/{projectId}/orders/portIns { "desiredPortSchedule": { "desiredPortDate": "2024-09-25", }, "phoneNumbers": [ { "phoneNumber": "+12345678901", "voiceConfiguration": { "type": "EST", "trunkId": "123456" }, "portOutInfo": { "existingPortOutPin": "1234" }, "endUser": { "name": "John Doe", "streetName": "Main St", "streetNum": "123", "city": "Anytown", "state": "NY", "zipCode": "12345" }, } ] } ``` #### Lifetime of a port order If everything is correct, the order run thru is life cycle and keep you updated on changes but hopefully nothing will change and the number will be ported in on the desired port date. If more information is needed from you, it will be communicated to you via the order notes and error statuses on the individual numbers. And you reply with a note or update your order with required information. It's not uncommon for a port order to be a few days or weeks in the making, so don't worry if you don't receive an update right away. ### Port-In phone numbers When you port in phone numbers to Sinch you need to make sure the numbers are portable, you can use the portability check to make sure the numbers are portable before creating an order. - name: Webhooks description: |- ## Webhooks for porting Sinch uses webhooks to notify you of events that happen in the porting system. You can configure webhooks for porting events in the porting defaults API or via the dashboard. Anytime a port is then made via the dashboard or we at Sinch trigger an update we will call your webhook url with the event type and a payload depending on event type. - name: Port-in settings description: Porting default settings - name: Advanced porting description: |- This section is for advanced porting operations, like on demand activating numbers, getting available numbers for activation, and more. If you are looking for basic porting operations like creating an order, checking portability, and more, please refer to the Port-in numbers section. ### Scheduled ports The recommended way to port numbers to Sinch is to schedule the port, this means that you create an order and specify a desired port date and time, this is the date you want the numbers to be ported in to Sinch automatically and we will sync with the loosing carrier to make sure the port is done on that date with minimal downtime for you and your customers. ### On demand ports If you need to control your self when a number is activated you can use on demand ports, that means as soon as the number is confirmed you can activate it when you want. And we take care of the rest. When using on demand ports you need to make sure the number is confirmed and released for activation. you can also choose to activate numbers on activation groups. ### Activation groups When you create a port in order we assign an activating group on the numbers, the grouping is by carrier so if you have a large port-in order from multiple different carriers you can group and look at the numbers by group to see status. Updates to port order usually comes on group basis and are confirmed ro rejected on carrier level. You can also use this as a way to activate groups for on-demand activation. However we recommend you porting in numbers by carrier to make sure you get the best experience. ### On demand activation When you set up an order with onDemandActivation set to true, you can activate the numbers when you want. This is useful if you want to control when the numbers are activated. You can activate a whole order by calling /orders/portins/{orderId}/activate or you can activate a specific group of numbers by calling /orders/portins/{orderId}/activate with the phoneNumberGroup you find on the number. Please note that it is not possible to activate single numbers by order or activation group. - name: Error Messages description: |- ## Error Messages Request errors are returned as HTTP status codes. The following table lists the possible error codes and their meaning. The type will give you a general idea of why the operation failed, whereas the errorCode describes the issue in more detail. Below we list the error_codes for the API, segmented by their corresponding error_type. ## Http Error Codes ### 400 - Bad Request ```json { "code": "404", "error": "Bad Request", "message": " The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications. It could be invalid JSON, missing required fields, or other issues." } ``` ### 401 - Unauthorized Empty body, or you have the wrong API key, secret, or project. ### 402 - Payment required ```json { "code": "402", "error": "Payment required", "message": "You have reached 0 balance on your account please make a payment." } ``` ### 404 - Not found ```json { "code": "404", "error": "Not found", "message": "The resource is not found, not available, or does not exist." } ``` ### 422 - Unprocessable Content (Invalid parameters) ```json { "code": "422", "error": "Invalid parameters", "message": "The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications." details: { fieldViolations: [ { field: "to", description: "The (+15551) is not a valid phone number" } ] } ``` ### 429 Rate limit exceeded Rate limit exceeded, please back off and try again later. If you need higher rate please contact support. ### 500 - Internal Server Error Probably no body, but if there is a body it will look like this: ```json { "code": "500", "error": "Internal service error", "message": "Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support." } ``` ## Error object Please note that the response code is probably the most important part of the response, but the error object will contain more information about the error. Not all errors return this object, and the `details` object is not always present. security: - basicAuth: [] - bearerAuth: [] paths: /configuration: post: operationId: createConfiguration tags: - Port-in settings summary: Create Configuration description: Create default Configuration for a given project requestBody: required: true description: Create Communication Configuration for a given project content: application/json: schema: $ref: '#/components/schemas/DefaultsConfiguration' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/DefaultsConfiguration' get: operationId: getConfiguration tags: - Port-in settings summary: Get Configuration description: Retrieve Notification Configuration for a given project responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/DefaultsConfiguration' put: operationId: updateConfiguration tags: - Port-in settings summary: Update configuration description: Update default configurations for a given project requestBody: required: true description: Update default configurations for a given project content: application/json: schema: $ref: '#/components/schemas/DefaultsConfiguration' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/DefaultsConfiguration' /portabilityChecks: post: tags: - Port-in numbers operationId: checkPortingAvailability summary: Porting availability description: Use this before creating a order to make sure all numbers are available for port in to Sinch. Please not that if you try to port a number that is not portable the order will fail. requestBody: required: true content: application/json: schema: type: object properties: phoneNumbers: type: array items: type: string example: "+12311234567" responses: '200': description: Successful operation content: application/json: schema: type: object properties: phoneNumbers: type: array items: type: object properties: phoneNumber: type: string example: "+12345678901" portable: type: boolean carrier: type: string example: "T-Mobile" reason: type: string description: Optional, included only if not portable /orders/portIns: post: operationId: orderPortIn tags: - Port-in numbers summary: Create port-in order description: |- Create an order to port phone numbers from another carrier into Sinch. Refer to the Port-In Status section for more information on port-in order updates. Please note that order will fail if you try to port numbers that are not portable, so you should always use the portability check before creating an order. Note: For port orders of over 500 numbers, please contact the [support team](https://tickets.sinch.com/plugins/servlet/desk/portal/31/create/1572). **Note:** In order to send SMS and MMS messages in the US using 10DLC phone numbers, all messages must be sent via an approved campaign. Your campaigns are managed under US 10DLC Campaigns in the SMS section. A number can be associated to an approved campaign after the port completes. requestBody: required: true description: Order Port-In phone numbers content: application/json: schema: required: - desiredPortSchedule - phoneNumbers $ref: '#/components/schemas/OrderBaseItem' example: desiredPortSchedule: desiredPortDate: "2025-01-31" desiredPortTime: "10:00:00" desiredPortTimeZone: "US/Eastern" phoneNumbers: - phoneNumber: "+12345678901" voiceConfiguration: type: "EST" trunkId: "123456" portOutInfo: existingPortOutPin: "1234" endUser: name: "John Doe" streetName: "Main St" streetNum: "123" city: "Anytown" state: "NY" zipCode: "12345" responses: '201': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OrderBaseItem' get: tags: - Port-in numbers operationId: getPortInOrders summary: List port-in orders description: Retrieve a list of port-in based on the search parameters, you can also specify view here to get less detail parameters: - in: query name: orderId schema: type: number description: Search by the ID of the order. - in: query name: orderStatus schema: $ref: '#/components/schemas/OrderStatus' description: Search by the status of the order. - in: query name: customerOrderReference description: The reference you specified when creating the order. schema: type: string - in: query name: createdDateStart schema: type: string description: "Search by the created date. This query sets the start date of the search period. Date Format: yyyy-mm-dd." - in: query name: createdDateEnd schema: type: string description: "Search by the created date. This query sets the end date of the search period. Date Format: yyyy-mm-dd." - in: query name: phoneNumber description: Search by a phone number. schema: type: string - in: query name: focStartDate schema: type: string format: date-time description: "Search by the firm order confirmation. This query sets the start date of the search period. Date format: yyyy-mm-dd." - in: query name: focEndDate schema: type: string format: date-time description: "Search by the firm order confirmation. This query sets the end date of the search period. Date format: yyyy-mm-dd." - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/Page" # - in: query # name: searchId # description: If you are retrieving a large list of orders, and are using pagination, on subsequent page queries # schema: # type: string responses: '200': description: Successful operation content: application/json: schema: allOf: - type: object properties: orders: type: array items: $ref: "#/components/schemas/OrderListItem" - $ref: "#/components/schemas/Pagination" /orders/portIns/{orderId}/availableActivations: get: operationId: getPortInAvailableActivation tags: - Advanced porting description: |- Retrieve Port-In Order Available Activation Groups This operation allows you to get a list of phone number groups currently available for activation on a port-in order. FOC (portDate) must be today or earlier, and the numbers must be in routing on the Sinch network. summary: List port-in activation groups parameters: - in: path name: orderId schema: type: string example: 897867 required: true responses: '200': description: Successful operation content: application/json: schema: type: array items: type: object properties: phoneNumberGroup: type: string example: "GW Verizon Grp1" focDate: type: string phoneNumbers: type: array items: type: object properties: phoneNumber: type: string voiceConfiguration: $ref: '#/components/schemas/VoiceConfiguration' smsConfiguration: $ref: '#/components/schemas/SmsConfiguration' /orders/portIns/{orderId}/activate: post: tags: - Advanced porting operationId: activatePortIn summary: On demand activation description: |- Activate numbers that are ready to be ported. Confirmation date (FOC) must be today or earlier, and the numbers must be in routing on the Sinch network (occurs at midnight on the date of the port, after concurrence, or following the 18-hour wireline port timer expiration on expedited ports). **Note:** In order to send SMS and MMS messages in the US using 10DLC phone numbers, all messages must be sent via an approved campaign. Your campaigns are managed under US 10DLC Campaigns in the SMS section. A number can be associated to an approved campaign after the port completes. parameters: - in: path name: orderId schema: type: string example: 897867 required: true requestBody: required: false description: Activate Port-In Order content: application/json: schema: type: object properties: phoneNumberGroups: type: array items: type: string responses: '200': description: Successful operation content: application/json: schema: type: object properties: phoneNumberGroups: type: array items: type: object properties: phoneNumberGroup: type: string status: type: string /orders/portIns/{orderId}: get: tags: - Port-in numbers operationId: getOrderDetails summary: Get order Detail description: |- Get details about an existing order along with order notes and process notes (for Port-In orders). For realtime updates on the order status, please refer to the Webhooks section. wich is the recommended way to get updates on the order status. parameters: - in: path name: orderId schema: type: number required: true description: Order Identifier example: 897867 responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OrderBaseItem' delete: tags: - Port-in numbers operationId: deleteOrder summary: Cancel Pending Order description: This operation allows you to cancel an order in Pending status. parameters: - in: path name: orderId schema: type: number required: true description: Order Identifier example: 897867 responses: '200': description: Successful operation put: operationId: updatePortInOrder tags: - Port-in numbers summary: Update port-in order description: This operation allows you to update information on a Pending order. Please note that you need to send the full object, its not a patch parameters: - name: orderId in: path required: true schema: type: string description: The unique identifier for the order. requestBody: required: true description: Update Pending Order content: application/json: schema: $ref: '#/components/schemas/OrderBaseItem' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/OrderBaseItem' /orders/portIns/{orderId}/notes: post: tags: - Port-in numbers operationId: addOrderNote summary: Add Order Note description: This operation allows you to add a note to an existing order. parameters: - in: path name: orderId schema: type: number required: true description: Order Identifier requestBody: required: true description: Add Order Note content: application/json: schema: type: object properties: note: type: string responses: '200': description: Successful operation content: application/json: schema: type: object properties: id: type: number note: type: string /orders/portIns/{orderId}/documents: post: operationId: addOrderDocuments tags: - Port-in numbers summary: Add Order Document description: This operation allows you to add a document to an existing order. parameters: - in: path name: orderId schema: type: number required: true description: Order Identifier requestBody: required: true description: Add Order Document content: application/json: schema: $ref: '#/components/schemas/OrderDocumentWithContent' responses: '200': description: Successful operation, the file name/description would be returned, but the content would not be returned in the response. content: application/json: schema: $ref: '#/components/schemas/OrderDocumentBase' /orders/{orderId}/documents/{documentId}: get: operationId: getOrderDocumentContent tags: - Port-in numbers summary: Get document content description: This operation allows you to retrieve specific document contents attached to an existing order. parameters: - in: path name: orderId schema: type: number required: true description: Order Identifier - in: path name: documentId description: Document content for schema: type: string required: true responses: '200': description: Successful operation content: application/json: schema: allOf: - type: object properties: documentId: type: number - $ref: '#/components/schemas/OrderDocumentWithContent' - type: object properties: contentType: type: string # /internal/orders/portIns/phoneGroups/{orderId}: # get: # tags: # - Internal APIs # operationId: getPortInOrdersAsPhoneGroups # summary: List port-in orders # description: Retrieve a list of port-in based on the search parameters, you can also specify view here to get less detail # parameters: # - in: path # name: orderId # schema: # type: number # required: true # responses: # '200': # description: Successful operation # content: # application/json: # schema: # allOf: # - type: object # properties: # id: # type: number # status: # type: string # createdDate: # type: string # notes: # type: array # items: # $ref: '#/components/schemas/OrderNote' # documents: # type: array # items: # $ref: '#/components/schemas/OrderDocumentBase' # customerOrderReference: # type: string # description: Your reference you specified when creating the order # example: "123456" # default: "" # onDemandActivation: # type: boolean # description: |- # If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. # If true the numbers will be activated as when you call `:activate`, if false they will be activated on the desiredPortDate # default: false # desiredPortSchedule: # description: The date and time you want the numbers to be ported in, if you set a Time in defaults that time will be used if no time is set # $ref: '#/components/schemas/DesiredPortDateTime' # - type: object # properties: # phoneNumberGroups: # type: array # items: # $ref: '#/components/schemas/PhoneNumberGroupItem' webhooks: OrderUpdated: post: operationId: order summary: Order Updated description: |- This operation allows you to get a webhook when an order is updated. This is a webhook that will be called when an order is updated, it will contain the order and the status of the order. tags: - Webhooks requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderWebhookStatusEvent' example: type: ORDER_UPDATED orderId: "897867" order: id: 897867 customerOrderReference: "123456" desiredPortSchedule: desiredPortDate: "2024-09-24" desiredPortTime: "09:00:00Z" status: "PENDING" onDemandActivation: false phoneNumbers: - phoneNumber: "+12345678901" portOutInfo: existingPortOutPin: "1234" endUser: name: "John Doe" streetName: "Main St" streetNum: "123" city: "Anytown" state: "NY" zipCode: "12345" voiceConfiguration: type: "EST" trunkId: "123456" NumbersActivated: post: operationId: numbersActivated summary: Number activated description: |- At least one number on the port order was activated tags: - Webhooks requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/NumberStatusWebhookStatusEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [NUMBERS_ACTIVATED] default: NUMBERS_ACTIVATED example: type: NUMBERS_ACTIVATED orderId: 897867 phoneNumbers: - phoneNumber: "+12345678901" status: Activated activatedDate: "2024-09-24T12:00:00Z" NumbersConfirmed: post: operationId: NumbersConfirmed summary: Number confirmed description: |- At least one number on the port order was confirmed, this means that the number is ready to be activated if `onDemandActivation` was set to true or if it will be activated at the specified confirmation date tags: - Webhooks requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/NumberStatusWebhookStatusEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [NUMBERS_CONFIRMED] default: NUMBERS_CONFIRMED example: type: NUMBERS_CONFIRMED orderId: 897867 phoneNumbers: - phoneNumber: "+12345678901" status: Confirmed confirmedDate: "2024-09-24T12:00:00Z" NumbersRejected: post: operationId: NumbersRejected summary: Number Rejected description: |- At least one number on the port order was rejected, look at rejected reasons for more details on what went wrong tags: - Webhooks requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/NumberStatusWebhookStatusEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [NUMBERS_REJECTED] default: NUMBERS_REJECTED example: type: NUMBERS_REJECTED orderId: 897867 phoneNumbers: - phoneNumber: "+12345678901" status: Confirmed confirmedDate: "2024-09-24T12:00:00Z" NewOrderNote: post: operationId: NewOrderNote summary: Note added to order description: |- A note was added to the order either by Sinch or you tags: - Webhooks requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/NewNoteWebhookStatusEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [NEW_ORDER_NOTE] default: NEW_ORDER_NOTE example: type: NEW_ORDER_NOTE orderId: 897867 note: "This is a note" components: parameters: Page: in: query name: page description: The page you want to retrieve returned from a previous List request, if any schema: type: string PageSize: name: pageSize in: query description: The maximum number of items to return per request. The default is 100 and the maximum is 1000. If you need to export larger amounts and pagination is not suitable for you can use the Export function in the dashboard. schema: type: integer maximum: 1000 minimum: 1 schemas: Pagination: type: object readOnly: true properties: page: readOnly: true type: integer description: Current page totalPages: readOnly: true type: integer description: Total number of pages. pageSize: readOnly: true type: integer description: Number of items per page. totalItems: type: integer readOnly: true format: int32 description: Total size of the result. WebhookEvent: type: object properties: event: type: string description: The event that triggered the webhook enum: [ORDER_UPDATED, NUMBERS_ACTIVATED,NUMBERS_CONFIRMED,NUMBERS_REJECTED, NEW_ORDER_NOTE] x-enumDescriptions: ORDER_UPDATED: "The order was updated it can be status or any other updates to a pending order" NUMBERS_ACTIVATED: "at least one number was activated" NUMBERS_CONFIRMED: "At least one number was confirmed" NUMBERS_REJECTED: "At least one number was rejected" NEW_ORDER_NOTE: "A new note was added to the order" orderId: type: string description: The order id that was updated OrderWebhookStatusEvent: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [ORDER_UPDATED] default: ORDER_UPDATED x-enumDescriptions: ORDER_UPDATED: "The order was updated it can be status or any other updates to a pending order" order: $ref: '#/components/schemas/OrderBaseItem' NumberStatusWebhookStatusEvent: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object properties: event: type: string description: The event that triggered the webhook enum: [NUMBERS_ACTIVATED, NUMBERS_CONFIRMED, NUMBERS_REJECTED] default: NUMBERS_ACTIVATED phoneNumbers: type: array items: $ref: '#/components/schemas/PhoneNumberMinItem' NewNoteWebhookStatusEvent: allOf: - $ref: '#/components/schemas/WebhookEvent' - type: object properties: note: type: string description: The note that was added OrderStatus: type: string enum: [PENDING, CONFIRMED, COMPLETED, PENDING_CANCELATION, CANCELED] readOnly: true x-enumDescriptions: ORDER_BUILDING: "The order is being created" PENDING: "The order is pending, and can be updated" CONFIRMED: "The order is confirmed, and can not be updated but if onDemand is true it can be activated" COMPLETED: "The order is completed, the port has completed and the numbers are active" PENDING_CANCELATION: "The order is in the process of being cancelled. During this time you can not submit same numbers on a new order" CANCELED: "The order is cancelled, either by the customer or by the system" PageSort: type: object properties: size: type: number page: type: number DefaultsConfiguration: type: object properties: contact: type: object properties: email: type: string name: type: string phone: type: string webhookUrl: type: string defaultPortTime: type: string description: The default time for porting in numbers. If you don't specify a time in the order this time will be used. example: "09:00:00" defaultPortTimeZone: type: string enum: [US/Eastern, US/Central, US/Mountain, US/Pacific] x-enumDescriptions: US/Eastern: US Eastern Timezone US/Centra: US Central Timezone US/Mountain: US Mountain Timezone US/Pacific: US Pacific Timezone description: The default time zone for porting in numbers. If you don't specify a time zone in the order, this time zone will be used. DesiredPortDateTime: required: - desiredPortDate type: object properties: desiredPortDate: type: string description: The date you want the numbers to be ported in, in ISO format. example: 2025-01-31 desiredPortTime: type: string example: "09:00:00" description: The time you want the numbers to be ported in. desiredPortTimeZone: type: string enum: [US/Eastern, US/Central, US/Mountain, US/Pacific] x-enumDescriptions: US/Eastern: US Eastern Timezone US/Central: US Central Timezone US/Mountain: US Mountain Timezone US/Pacific: US Pacific Timezone description: The time zone you want to use for the desired port time. example: US/Eastern OrderBaseItem: type: object required: - desiredPortSchedule properties: id: type: number description: The unique identifier for the order readOnly: true example: 890192331 status: $ref: "#/components/schemas/OrderStatus" customerOrderReference: type: string description: Your reference you specified when creating the order example: "123456" default: "" onDemandActivation: type: boolean description: |- If you use onDemand activation you will need to make sure the numbers are both confirmed and released for activation, if you don't use onDemand the numbers will be activated on the desiredPortDate is the recommended way. If true the numbers will be activated as when you call `:activate`, if false they will be activated on the desiredPortDate default: false desiredPortSchedule: description: |- The date and time you want the numbers to be ported in. If you set a `defaultPortTime` and `defaultPortTimeZone` in defaults those settings will be used if not set per order. If you haven't set defaults and do not set the time and time zone on the order the system default will be used. **System Default Time:** 09:00:00 US/Eastern $ref: '#/components/schemas/DesiredPortDateTime' phoneNumbers: type: array title: Phone numbers description: The numbers for the order in e164 format items: $ref: '#/components/schemas/PhoneNumberMinItem' notes: readOnly: true description: Notes if any on the order, you will get notes if there is any problems with the order and you send notes as reply to those problems type: array items: $ref: '#/components/schemas/OrderNote' documents: readOnly: true description: Documents if any on the order, you will get documents if there is any problems with the order and you send documents as reply to those problems type: array items: $ref: '#/components/schemas/OrderDocumentBase' createdDate: readOnly: true description: When the order was created type: string format: date-time resellerName: type: string description: |- **This is requirement for canadian numbers only, we need to figure out what we expect here and where the customer can find this info** default: "" PhoneNumberGroupItem: type: object description: We group phone numbers by carrier so you can see the status of the numbers by carrier properties: phoneNumberGroup: type: string focDate: type: string phoneNumbers: type: array items: allOf: - $ref: '#/components/schemas/PhoneNumberItem' OrderListItem: type: object properties: id: type: number description: The unique identifier for the order readOnly: true example: 890192331 status: $ref: "#/components/schemas/OrderStatus" customerOrderReference: type: string description: Your reference you specified when creating the order example: "123456" default: "" createdDate: readOnly: true description: When the order was created type: string format: date-time phoneNumberQuantity: type: number readOnly: true description: The number of phone numbers in the order, a helper property for you, this can also be done by and counting on the `numbers` collection focQuantity: type: number readOnly: true description: The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the `numbers` collection and filtering on status `CONFIRMED` activatedQuantity: type: number readOnly: true description: The number of phone numbers that are activated, The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the `numbers` collection and filtering on status `COMPLETE` rejectedQuantity: type: number readOnly: true description: The number of phone numbers that are rejected, This can be done by counting on the `phoneNumbers` collection and filtering on status `REJECTED` excludedQuantity: type: number readOnly: true description: The number of phone numbers that are activated, The number of phone numbers that are confirmed, a helper property for you, this can also be done by and counting on the `numbers` collection and filtering on status `EXCLUDED` PortOutItem: type: object description: The port out information at the loosing carrier for the number, usually only port-out pin is required properties: existingPortOutPin: type: string accountNum: type: string accountPhoneNumber: type: string authorizingName: type: string description: Name of the person authorizing the port in authorizingDate: type: string description: Date of authorizing the port in (must be today or earlier and cannot be in the future) PhoneNumberMinItem: type: object description: "a phone port item" required: - phoneNumber - endUser $ref: '#/components/schemas/PhoneNumberItem' PhoneNumberItem: type: object required: - phoneNumber - endUser - portOutInfo properties: phoneNumber: type: string format: e164 example: "+12345678901" status: type: string default: PENDING readOnly: true enum: [PENDING, CONFIRMED, REJECTED, ACTIVATED, CANCELED, EXCLUDED] x-enumDescriptions: PENDING: "The number is pending, and can be updated" CONFIRMED: "The number is confirmed, and can not be updated but if onDemand is true it can be activated" REJECTED: "The number is rejected, look at the rejectReason for more details it can be either its not portable or wrong port out info" ACTIVATED: "The number is activated" CANCELED: "The number is cancelled, either by the customer or by the system" EXCLUDED: The number is excluded from the order, look at the exclusionReason for more details exclusionReason: description: "If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion." type: string readOnly: true default: "" exclusionTime: description: |- If the phone number is excluded or rejected, the status here would reflect as such. In this case, there would be exclusion reason along with date of exclusion. type: string readOnly: true format: date-time countryCode: description: The country code of the number ISD code US, SE etc. At the moment only north american numbers are supported type: string readOnly: true example: US activateTime: description: the time the number was activated UTC timezone type: string readOnly: true example: "14:00" activateUser: readOnly: true description: The user that activated the number type: string voiceConfiguration: description: if specified will override the voice configuration for the order $ref: '#/components/schemas/VoiceConfiguration' smsConfiguration: description: if specified will override the sms configuration for the order $ref: '#/components/schemas/SmsConfiguration' endUser: description: if specified will override the endUser for the order $ref: '#/components/schemas/EndUser' portOutInfo: description: if specified will override the endUser for the order $ref: '#/components/schemas/PortOutItem' features: $ref: '#/components/schemas/Feature' newPortOutPin: type: string rejectReason: readOnly: true type: string description: The reason the number was rejected excludedFeatures: readOnly: true type: array items: type: object properties: featureName: type: string exclusionReason: type: string phoneNumberGroup: readOnly: true type: string example: "GW Verizon Grp1" focDate: description: |- Once the phone number has a firm order confirmation date, it will be returned as part of the phone number details. readOnly: true type: string format: date-time OrderNote: type: object properties: note: type: string description: The actual message createdTime: type: string description: UTC iso https://www.ietf.org/rfc/rfc3339.txt createdBy: type: string OrderDocumentBase: type: object properties: id: type: number readOnly: true documentName: type: string description: type: string OrderDocumentWithContent: type: object allOf: - $ref: '#/components/schemas/OrderDocumentBase' - type: object properties: fileContent: type: string description: Base64 encoded content representing the file contents. SmsConfiguration: type: object description: Configuration for what sms service id to use, and other sms related configurations properties: smsAppId: type: string RTCConfiguration: type: object title: RTC summary: RTC voice configuration description: If you want to use the number with programmable voice properties: type: type: string enum: [RTC] default: RTC appId: type: string description: The app id from the dashboard where you want to use the number example: "6afd2da3-1692-4443-834c-8a2f386ec284" ESTConfiguration: type: object title: EST description: When you want to use the number for elastic sip trunking properties: type: type: string enum: [EST] default: EST trunkId: type: string example: "01G65Z755AFWAKHE12NY0CQ9FH" FAXConfiguration: type: object title: FAX description: When you want to use the number for fax properties: type: type: string enum: [FAX] default: FAX serviceId: type: string example: 01G65Z755GHWAKHE12NY0CQO0T VoiceConfiguration: description: Configuration for voice discriminator: propertyName: type mapping: RTC: "#/components/schemas/RTCConfiguration" EST: "#/components/schemas/ESTConfiguration" FAX: "#/components/schemas/FAXConfiguration" oneOf: - $ref: '#/components/schemas/RTCConfiguration' - $ref: '#/components/schemas/ESTConfiguration' - $ref: '#/components/schemas/FAXConfiguration' # ExcludedPhoneNumberItem: # type: object # properties: # phoneNumber: # type: string # excludedReason: # type: string # dateOfExclusion: # type: string Feature: type: object properties: e911: type: object properties: name: type: string streetNum: type: string streetInfo: type: string location: type: string city: type: string state: type: string postalCode: type: string postalCodePlusFour: type: string enhStreetNum: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhStreetInfo: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhLocation: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhCity: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhState: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhPostalCode: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true enhPostalCodePlusFour: description: Once E911 Address validation is completed, "enh" (enhanced) attributes are populated type: string readOnly: true EndUser: type: object required: - name - streetNum - streetName - city - state - zipCode properties: name: type: string description: The name of the end user can be person or company name, please not if you are not using this your self it should be the name/company of the actual user. example: Joe Doe streetNum: description: The street number type: string example: 123 streetName: type: string example: Main St streetPreDir: type: string default: "" example: N streetType: type: string default: "" example: Court streetPostDir: type: string default: "" example: SW locationType1: type: string description: your own location information surch as suite etc use this to describe it example: Suite locationValue1: description: your own location information surch as suite etc, put value here type: string example: 2134 locationType2: type: string example: "" default: "" locationValue2: type: string example: "" default: "" locationType3: type: string example: "" default: "" locationValue3: type: string example: "" default: "" city: description: The city of the end user type: string example: Anytown state: type: string description: State two letter abbreviation example: CA zipCode: type: string example: "12345" default: "" typeOfService: type: string description: Available values are B, Business, R, and Residence enum: [B,R] x-enumDescriptions: B: "Business" R: "Residence" example: B default: B Error: type: object properties: code: description: HTTP status code or error code readOnly: true type: integer format: int32 example: 400 status: description: Response status name. readOnly: true type: string example: INVALID_ARGUMENT message: type: string readOnly: true description: A developer-facing error message example: Bad request. details: readOnly: true description: Details of the errors type: array items: $ref: "#/components/schemas/ErrorDetail" ErrorDetail: type: object anyOf: - $ref: "#/components/schemas/NotFoundDetail" - $ref: "#/components/schemas/BadRequestDetail" - $ref: "#/components/schemas/ErrorInfo" discriminator: propertyName: type mapping: NotFound: "#/components/schemas/NotFoundDetail" BadRequest: "#/components/schemas/BadRequestDetail" ErrorInfo: "#/components/schemas/ErrorInfo" NotFoundDetail: type: object description: The request was malformed on one or more fields. x-internal: https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169 properties: type: type: string description: The request was malformed on one or more properties. readOnly: true example: NOT_FOUND default: BadRequest ErrorInfo: description: |- Describes the cause of the error with structured details. Example of an error when trying to make a call to blocked destination: { "reason": "DESTINATION_BLOCKED" "domain": "VOICE" "metadata": { "country": "Bermuda", } } type: object properties: type: type: string description: |- Describes the cause of the error with structured details. Example of an error when trying to make a call to blocked destination: ``` { "reason": "DESTINATION_BLOCKED" "domain": "VOICE" "metadata": { "country": "Bermuda", } } ``` default: ErrorInfo example: ErrorInfo reason: type: string description: |- The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique. Max 63 characters and match /[A-Z0-9_]+/. maxLength: 63 domain: type: string description: Domain for error, for voice it is always `sinch.voice`. metaData: description: Additional structured details about this error. key value pair of strings type: object BadRequestDetail: type: object description: The request was malformed on one or more fields. x-internal: https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169 properties: type: type: string description: The request was malformed on one or more properties. readOnly: true example: BadRequest default: BadRequest fieldViolations: description: The field violation(s). type: array items: $ref: "#/components/schemas/FieldViolation" example: [ { "field": "to", "description": "Phone number was not in the expected format.", }, ] FieldViolation: type: object properties: field: type: string readOnly: true description: Request field. example: to description: type: string readOnly: true description: Description of why the request field was considered invalid. example: Phone number was not in the expected format. securitySchemes: basicAuth: type: http scheme: basic description: Your key ID and Key secret serve as the username and password, respectively. Both can be found in the Sinch Customer Dashboard.For more information about basic authentication in the Numbers API, click [here](/docs/numbers/api-reference/authentication/basic). bearerAuth: type: oauth2 description: The username and password are your Key ID and Key Secret from the Access keys section in the Sinch Customer Dashboard. Exchange these for a bearer token (access token). Learn how [here](/docs/numbers/api-reference/authentication/oauth). If you are using the Beta experience on your Customer Dashboard account, find your credentials here instead. flows: clientCredentials: tokenUrl: https://auth.sinch.com/oauth2/token scopes: {}