Routing

Add Inbound Route

An Inbound Route can be created to configure ClearIP to return a SIP 302 response with a specified list of route destinations in a Contact header. The SBC or softswitch will attempt to route the call in Routes may be configured to apply to specific LATA, SPID, called number prefix, SBC, Service Provider, Group, User. ClearIP can return route destinations as any combination of IP addresses, domain names, or trunk group IDs.

The Prefix field refers to requested called number regardless of whether the number has been ported.

The Route Prefix fields can be used to prepend a static set of characters or numbers in front of the Contact header user of the specified destination.

The Route Destinations refer to the IP address, trunk group numbers, or domain names that ClearIP should return in the Contact header. ClearIP will return routes in the order of Primary Route Destinations first, Secondary Route Destinations and so on. The SBC or softswitch will attempt to route the call, failing over according to the ordered list of routes in the SIP 302 Contact header.

If the Inbound Routes should be restricted to apply to inbound calls, the relevant Service Provider, Group, User, or Operator must be specified.

The Inbound Route table is searched by ClearIP before the Outbound Routes table.

Method: POST URL: https://api.clearip.com/inboundRoutes

Request Body:

{
  "inboundRoute": {
    "lata": "OPTIONAL_LATA_HERE",
    "spid": "OPTIONAL_SPID_HERE",
    "prefix": "CALLED_NUMBER_PREFIX_HERE ",
    "primaryRoutePrefix": "ROUTE_PREFIX_HERE",
    "primaryRouteDestinations": "ROUTE_DESTINATION_HERE",
    "secondaryRoutePrefix": "",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": NUMBER_OF_DESTINATIONS_TO_RETURN_PER_ROUTE,
    "comment": "COMMENT_HERE",
    "callingNumber": "OPTIONAL_CALLING_NUMBER_HERE",
    "sbc": OPTIONAL_SBC_HERE,
    "serviceProvider": OPTIONAL_SERVICE_PROVIDER_HERE,
    "group": OPTIONAL_GROUP_HERE,
    "user": OPTIONAL_USER_HERE,
    "callingCountry": OPTIONAL_CALLING_COUNTRY_HERE
  }
}

Example Response Body:

{
  "inboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "lata": "",
      "spid": "",
      "prefix": "14045266060",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

Delete Inbound Route

Method: DELETE URL: https://api.clearip.com/inboundRoutes/INBOUND_ROUTE_ID_HERE

Example Request Method: DELETE URL: https://api.clearip.com/inboundRoutes/99999999-9999-4999-9999-999999999999

Example Response:

{
  "inboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "lata": "",
      "spid": "",
      "prefix": "14045266060",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

View Inbound Route

Method: GET URL: https://api.clearip.com/inboundRoutes?limit=20&skip=0&sort=prefix%20ASC

Example request: Pull Inbound Routes for a specific prefix 14045266060

Method: GET

URL: https://api.clearip.com/inboundRoutes?limit=20&skip=0&sort=prefix%20ASC&where%5Bprefix%5D%5BstartsWith%5D=14045266060

Update Inbound Route

Method: PATCH URL: https://api.clearip.com/inboundRoutes/INBOUND_ROUTE_ID_HERE

Example request: Update an existing Inbound Route with ID 99999999-9999-4999-9999-999999999999

Method: PATCH

URL: https://api.clearip.com/inboundRoutes/99999999-9999-4999-9999-999999999999

Request Body:

{
  "inboundRoute": {
    "lata": "OPTIONAL_LATA_HERE",
    "spid": "OPTIONAL_SPID_HERE",
    "prefix": "CALLED_NUMBER_PREFIX_HERE ",
    "primaryRoutePrefix": "ROUTE_PREFIX_HERE",
    "primaryRouteDestinations": "ROUTE_DESTINATION_HERE",
    "secondaryRoutePrefix": "",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": NUMBER_OF_DESTINATIONS_TO_RETURN_PER_ROUTE,
    "comment": "COMMENT_HERE",
    "callingNumber": "OPTIONAL_CALLING_NUMBER_HERE",
    "sbc": OPTIONAL_SBC_HERE,
    "serviceProvider": OPTIONAL_SERVICE_PROVIDER_HERE,
    "group": OPTIONAL_GROUP_HERE,
    "user": OPTIONAL_USER_HERE,
    "callingCountry": OPTIONAL_CALLING_COUNTRY_HERE
  }
}

Example Response Body:

{
  "inboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "lata": "",
      "spid": "",
      "prefix": "14045266060",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

Add Outbound Route

An Outbound Route can be created to configure ClearIP to return a SIP 302 response with a specified list of route destinations in a Contact header. The SBC or softswitch will attempt to route the call in Routes may be configured to apply to specific jurisdictions, LATA, SPID, prefix, SBC, Service Provider, Group, User. ClearIP can return route destinations as any combination of IP addresses, domain names, or trunk group IDs.

The Prefix field refers to either the LRN if a specific number has been ported or the beginning number digits if a number has not been ported.

The Route Prefix fields can be used to prepend a static set of characters or numbers in front of the Contact header user of the specified destination.

The Route Destinations refer to the IP address, trunk group numbers, or domain names that ClearIP should return in the Contact header. ClearIP will return routes in the order of Primary Route Destinations first, Secondary Route Destinations and so on. The SBC or softswitch will attempt to route the call, failing over according to the ordered list of routes in the SIP 302 Contact header.

If the Outbound Routes should be restricted to apply to outbound calls, the relevant Service Provider, Group, User, or Operator must be specified.

Method: POST URL: https://api.clearip.com/outboundRoutes

Request Body:

{
  "outboundRoute": {
    "jurisdiction": "international",
    "lata": "123",
    "spid": "1111",
    "prefix": "LRN_OR_CALLED_NUMBER_PREFIX_HERE ",
    "primaryRoutePrefix": "abc",
    "primaryRouteDestinations": "1.1.1.1",
    "secondaryRoutePrefix": "",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": 1,
    "comment": "COMMENT_HERE",
    "callingNumber": "",
    "sbc": null,
    "serviceProvider": null,
    "group": null,
    "user": null,
    "callingCountry": null
  }
}

Example Response Body:

{
  "outboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "jurisdiction": "international",
      "lata": "123",
      "spid": "1111",
      "prefix": "",
      "primaryRoutePrefix": "abc",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

Example: Route calls to specific LATA and SPID to a single IP address

Method: POST URL: https://api.clearip.com/outboundRoutes

Request Body:

{
  "outboundRoute": {
    "jurisdiction": "international",
    "lata": "438",
    "spid": "7473",
    "prefix": "",
    "primaryRoutePrefix": "",
    "primaryRouteDestinations": "1.1.1.1",
    "secondaryRoutePrefix": "",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": 1,
    "comment": "",
    "callingNumber": "",
    "reseller": null,
    "operator": null,
    "sbc": null,
    "serviceProvider": null,
    "group": null,
    "user": null,
    "callingCountry": null
  }
}

Response Body:

{
  "outboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "jurisdiction": "international",
      "lata": "438",
      "spid": "7473",
      "prefix": "",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

Example: Route 1-800 calls to a set of IP addresses for failover routing

Method: POST URL: https://api.clearip.com/outboundRoutes

Request Body:

{
  "outboundRoute": {
    "jurisdiction": "international",
    "lata": "",
    "spid": "",
    "prefix": "1800",
    "primaryRoutePrefix": "",
    "primaryRouteDestinations": "1.1.1.1",
    "secondaryRoutePrefix": "",
    "secondaryRouteDestinations": "2.2.2.2",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": 1,
    "comment": "",
    "callingNumber": "",
    "reseller": null,
    "operator": null,
    "sbc": null,
    "serviceProvider": null,
    "group": null,
    "user": null,
    "callingCountry": null
  }
}

Response Body:

{
  "outboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "jurisdiction": "international",
      "lata": "",
      "spid": "",
      "prefix": "1800",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

Delete Outbound Route

Method: DELETE URL: https://api.clearip.com/outboundRoutes/OUTBOUND_ROUTE_ID_HERE

Example Response:

{
  "outboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "jurisdiction": "international",
      "lata": "",
      "spid": "",
      "prefix": "14045266060",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}

View Outbound Route

Method: GET URL: https://api.clearip.com/outboundRoutes?limit=20&skip=0&sort=prefix%20ASC

Example request: Pull Outbound Routes for a specific prefix 14045266060

Method: GET

URL: https://api.clearip.com/outboundRoutes?limit=20&skip=0&sort=prefix%20ASC&where%5Bprefix%5D%5BstartsWith%5D=14045266060

Update Outbound Route

Method: PATCH URL: https://api.clearip.com/outboundRoutes/OUTBOUND_ROUTE_ID_HERE

Example request: Update an existing Outbound Route with ID 99999999-9999-4999-9999-999999999999

Method: PATCH

URL: https://api.clearip.com/outboundRoutes/99999999-9999-4999-9999-999999999999

Request Body:

{
  "outboundRoute": {
    "jurisdiction": "international",
    "lata": "",
    "spid": "",
    "prefix": "1800",
    "primaryRoutePrefix": "",
    "primaryRouteDestinations": "1.1.1.1",
    "secondaryRoutePrefix": "",
    "secondaryRouteDestinations": "2.2.2.2",
    "tertiaryRoutePrefix": "",
    "quaternaryRoutePrefix": "",
    "quinaryRoutePrefix": "",
    "destinationsPerRoute": 1,
    "comment": "",
    "callingNumber": "",
    "reseller": null,
    "operator": null,
    "sbc": null,
    "serviceProvider": null,
    "group": null,
    "user": null,
    "callingCountry": null
  }
}

Example Response:

{
  "outboundRoutes": [
    {
      "createdAt": 1577836800000,
      "updatedAt": 1577836800000,
      "id": "99999999-9999-4999-9999-999999999999",
      "jurisdiction": "international",
      "lata": "",
      "spid": "",
      "prefix": "14045266060",
      "primaryRoutePrefix": "",
      "primaryRouteDestinations": "1.1.1.1",
      "secondaryRoutePrefix": "",
      "secondaryRouteDestinations": "2.2.2.2",
      "tertiaryRoutePrefix": "",
      "tertiaryRouteDestinations": "",
      "quaternaryRoutePrefix": "",
      "quaternaryRouteDestinations": "",
      "quinaryRoutePrefix": "",
      "quinaryRouteDestinations": "",
      "destinationsPerRoute": 1,
      "comment": "",
      "callingNumber": "",
      "reseller": "99999999-9999-4999-9999-999999999999",
      "operator": "99999999-9999-4999-9999-999999999999",
      "sbc": null,
      "serviceProvider": null,
      "group": null,
      "user": null,
      "callingCountry": null
    }
  ]
}