Sinch Porting API

openapi: 3.2.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/legal
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.\nWhen 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.\nIf a number is not portable the whole order will fail.\nWhen porting a number to Sinch you can either use the dashboard or the API, the API is recommended for larger orders and for automation.\n\n**Note:** For port orders of over 500 numbers, please contact the [support team](https://support.sinch.com).\n\nThe 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,\nIf you have more advanced needs like on-demand activation, you can read more about that in the [advanced porting section](https://developers.sinch.com/docs/numbers/api-reference/porting/advanced-porting/).\n\n### Porting orders\n\nIn general you work with porting orders, a porting order is the resource that keeps the number(s) status and progress in one place.\n\nBefore 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.\n\n```json\nPOST /portabilityChecks\n{\n  \"phoneNumbers\": [\"+12345678901\"]\n}\n```\n\nIf the number is portable you can create an order like this:\n\n```json\nPOST v1/projects/{projectId}/orders/portIns\n    {\n      \"desiredPortSchedule\": {\n        \"desiredPortDate\": \"2024-09-25\",\n      },\n      \"phoneNumbers\": [\n        {\n          \"phoneNumber\": \"+12345678901\",\n          \"voiceConfiguration\": {\n            \"type\": \"EST\",\n            \"trunkId\": \"123456\"\n          },\n          \"portOutInfo\": {\n            \"existingPortOutPin\": \"1234\"\n          },\n          \"endUser\": {\n            \"name\": \"John Doe\",\n            \"streetName\": \"Main St\",\n            \"streetNum\": \"123\",\n            \"city\": \"Anytown\",\n            \"state\": \"NY\",\n            \"zipCode\": \"12345\"\n          },\n        }\n      ]\n    }\n    ```\n\n#### Lifetime of a port order\n\nIf 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.\nIf 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.\n\nIt'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.\n\n### Port-In phone numbers\n\nWhen 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\n\nRequest errors are returned as HTTP status codes. The following table lists the possible error codes and their meaning.\n\nThe 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.\n\n## Http Error Codes\n\n### 400 - Bad Request\n\n```json\n{\n  \"code\": \"404\",\n  \"error\": \"Bad Request\",\n  \"message\": \"\n    The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.\n    It could be invalid JSON, missing required fields, or other issues.\"\n}\n```\n\n### 401 - Unauthorized\n\nEmpty body, or you have the wrong API key, secret, or project.\n\n### 402 - Payment required\n\n```json\n{\n  \"code\": \"402\",\n  \"error\": \"Payment required\",\n  \"message\": \"You have reached 0 balance on your account please make a payment.\"\n}\n```\n\n\n### 404 - Not found\n\n```json\n{\n  \"code\": \"404\",\n  \"error\": \"Not found\",\n  \"message\": \"The resource is not found, not available, or does not exist.\"\n}\n```\n\n### 422 - Unprocessable Content (Invalid parameters)\n\n```json\n{\n  \"code\": \"422\",\n  \"error\": \"Invalid parameters\",\n  \"message\": \"The request could not be understood by the server due to malformed syntax.\n     The client SHOULD NOT repeat the request without modifications.\"\n  details: {\n    fieldViolations: [\n      {\n        field: \"to\",\n        description: \"The (+15551) is not a valid phone number\"\n      }\n    ]\n\n  }\n```\n\n### 429 Rate limit exceeded\n\nRate limit exceeded, please back off and try again later. If you need higher rate please contact support.\n\n\n### 500 - Internal Server Error\n\nProbably no body, but if there is a body it will look like this:\n\n```json\n{\n  \"code\": \"500\",\n  \"error\": \"Internal service error\",\n  \"message\": \"Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support.\"\n}\n```\n\n## Error object\n\nPlease 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.\nNot all errors return this object, and the `details` object is not always present."
security:
- basicAuth: []


# --- truncated at 32 KB (59 KB total) ---
# Full source: https://artifacts.apis.io/sinch/openapi/sinch-porting-api-openapi.yml