Requests

Schema

Specific action or operation that should take place

Type Object

Desc. id

Another format for UUID, used primarily for tasks, requests and messages.

One-Of

Types

• RequestAddCampaignNumbersData
• RequestAddMessagingNumbersData
• RequestAddVoiceNumbersData
• RequestNewNumbersData
• RequestRegisterBrandData
• RequestRegisterCampaignData
• RequestRemoveCampaignNumbersData
• RequestRemoveMessagingNumbersData
• RequestRemoveNumbersData
• RequestRemoveVoiceNumbersData
• RequestUnregisterBrandData
• RequestUnregisterCampaignData
• RequestVetBrandData

Example

{
  "error_code": "OK",
  "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "name": "SMS Tollfree Numbers 2021-08-12",
  "notes": "SMS Enablements",
  "status": "NEW",
  "type": "ADD_CAMPAIGN_NUMBERS",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "*": {
    "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
    "numbers": [
      "12003004000"
    ],
    "tcr_campaign_id": "C000000",
    "tmobile_enabled": true
  }
}

API

Updating An Existing Request

PATCH /api/v1/requests/{id} HTTP/1.1

Update an existing request.

Only the name and notes can be updated on the request once it has been checked out.

Path Parameters

Request

PATCH /api/v1/requests/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 533

{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "SMS Tollfree Numbers 2021-08-12",
    "notes": "SMS Enablements",
    "status": "NEW",
    "type": "ADD_CAMPAIGN_NUMBERS",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "*": {
      "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
      "numbers": [
        "12003004000"
      ],
      "tcr_campaign_id": "C000000",
      "tmobile_enabled": true
    }
  },
  "type": "request"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List Existing Requests

GET /api/v1/requests HTTP/1.1

Retrieve a list of all requests under the parent account

Query Parameters

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/requests HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 778

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "error_code": "OK",
        "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "name": "SMS Tollfree Numbers 2021-08-12",
        "notes": "SMS Enablements",
        "status": "NEW",
        "type": "ADD_CAMPAIGN_NUMBERS",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "*": {
          "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
          "numbers": [
            "12003004000"
          ],
          "tcr_campaign_id": "C000000",
          "tmobile_enabled": true
        }
      },
      "type": "request"
    }
  ]
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get Request

GET /api/v1/requests/{id} HTTP/1.1

Lookup a request by ID

Path Parameters

Request

GET /api/v1/requests/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

HTTP/1.1 200
Content-Type: application/json
Content-Length: 533

{
  "data": {
    "error_code": "OK",
    "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "name": "SMS Tollfree Numbers 2021-08-12",
    "notes": "SMS Enablements",
    "status": "NEW",
    "type": "ADD_CAMPAIGN_NUMBERS",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "*": {
      "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
      "numbers": [
        "12003004000"
      ],
      "tcr_campaign_id": "C000000",
      "tmobile_enabled": true
    }
  },
  "type": "request"
}

Response 403

application/json

HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json

HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Request Types

Requests have many subtypes which determine what kind of action will be taken, this can range from adding messaging-only numbers to removing existing numbers or just some of their components.

New Numbers

Request new numbers from inventory.

Parameters

Request for acquiring new numbers.

Type Object

Desc. min_quantity

Sometimes there are legitimately not enough numbers to fill the order.

The min_quantity or minimum quantity informs the system if you are willing to tolerate a smaller quantity.

Desc. npa

The 3 digit Area Code.

Desc. number_type

The wanted number type either TENDLC or TOLLFREE.

NONE is effectively a no-op or null.

Desc. numbers

If the numbers that should be provisioned are known ahead of time, they can be provided in this field, however normally you'll want to avoid using this due to reservations.

Desc. nxx

The 3 digit Exchange Code.

Desc. quantity

The maximum numbers that should be requested based on the search critierias.

This pairs with min_quantity to form a range.

Desc. rate_center

The rate center code.

Desc. state

The 2 character state code, such as FL for Florida.

Example

{
  "addons": {
    "messaging": {
      "api_key_ids": [
        "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
      ],
      "csp_campaign_id": "string",
      "enabled": false,
      "mms_enabled": true,
      "notes": "This is for a state child support centre and will be enabled on Campaign X.\n",
      "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "tcr_campaign_id": "C000000"
    },
    "voip_destinations": {
      "destinations": [
        {
          "activated": true,
          "auth_identity": "username",
          "auth_method": "BASIC",
          "auth_secret": "password",
          "destination": "http://example.com/http/route/call",
          "priority": 1,
          "type": "HTTP_ROUTE"
        }
      ],
      "enabled": true,
      "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "city": "string",
  "min_quantity": 10,
  "npa": "202",
  "number_type": "NONE",
  "numbers": [
    "12004005000"
  ],
  "nxx": "203",
  "quantity": 10,
  "rate_center": "NPLSFLGF3MD",
  "state": "FL"
}

Remove Numbers

A number can be deprovisioned with a REMOVE_NUMBERS request.

Parameters

Request data for removing existing numbers regardless of components.

This request can handle the removal of all components safely.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to remove

Example

{
  "numbers": [
    "12003004000"
  ]
}

Add Messaging Numbers

Messaging can be added to an existing number or messaging-only numbers provisioned using a ADD_MESSAGING_NUMBERS request.

Numbers provisioned by this request that are new to the parent account will be treated as as BYON (Bring-Your-Own-Number).

Parameters

Request for enabling numbers for messaging.

Note that this request handles two different kinds of enablements:

• BYON (Bring Your Own Number) type enablements, wheree a number will be registered for messaging only.
• Enabling messaging on an existing number.

Type Object

Desc. api_key_ids

A list of API Keys that should be bound to the numbers once enabled.

If the number is already bound to the listed keys, then nothing will change.

Note that this will add new keys and not replace the existing bindings.

Desc. message_class

The messaging class of the numbers to be provisioned, by default this will be A2P.

• A2P - Application to Person
• P2P - Person to Person

Desc. mms_enabled

Should the numbers be MMS enabled?

MMS can also be enabled later by simply toggling it via the DID API.

Note. If your account does not support MMS by default, then toggling this flag does nothing.

Desc. numbers

A list of NANP 11-digit numbers to enable messaging on.

Non-tollfree numbers can normally be enabled outside of some special cases.

For tollfree, additional action may be required before completion.

Desc. switch_id

The ID of the switch that should be attached to the did for messaging.

Note. This changes the DID's messaging switch, not its voice fallback one.

Leaving this field blank will not overwrite the existing switch.

Example

{
  "api_key_ids": [
    "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
  ],
  "message_class": "A2P",
  "mms_enabled": false,
  "numbers": [
    "12003004000"
  ],
  "switch_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
}

Remove Messaging Numbers

A number can have its messaging be deprovisioned with a REMOVE_MESSAGING_NUMBERS request.

Parameters

Request for disabling messaging on existing numbers.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to disable messaging for

Example

{
  "numbers": [
    "12003004000"
  ]
}

Register Brand

TCR Brands can be registered using a REGISTER_BRAND request.

If you are a CSP who is sharing a Campaign (and by extension brand) with Tychron, please use the TCR API and select Tychron as the CNP.

Parameters

Request for registering a TCR Brand.

Type Object

Desc. brand_id

A Universally unique identifier, which identifies the resource

Desc. cdr_id

A Universally unique identifier, which identifies the resource

Example

{
  "address1": "string",
  "alt_business_id": "string",
  "alt_business_id_type": "string",
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "brand_relationship": "string",
  "business_contact_email": "string",
  "cdr_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "city": "string",
  "company_name": "ACME Corp",
  "country_code": "string",
  "display_name": "ACME Corp Brand",
  "ein": "00000000",
  "ein_issuing_country_code": "US",
  "email": "string",
  "entity_type": "string",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "12003004000",
  "state": "string",
  "stock_exchange": "string",
  "stock_symbol": "string",
  "tcr_brand_id": "B000000",
  "tcr_csp_id": "S000000",
  "vertical": "string",
  "website": "string",
  "zip_code": "string"
}

Unregister Brand

Brands registered using REGISTER_BRAND can be removed using UNREGISTER_BRAND.

Parameters

Request for unregistering a TCR Brand.

Type Object

Example

{
  "brand_id": "89900e23-aafc-4b03-954d-0b11d3948042",
  "tcr_brand_id": "B000000"
}

Register Campaign

Registering a new campaign can be done with a REGISTER_CAMPAIGN request.

Parameters

Request Data for registering TCR Campaigns.

Please note: the completion of the Request does not signify that the Campaign is ready to accept numbers, please check for the dca_approved flag on the campaign itself, or listen for the CSP_CAMPAIGN_REGISTERED event via Subscription Events.

Type Object

Desc. tcr_campaign_id

TCR issued Campaign ID.

Desc. tcr_brand_id

TCR issued Brand ID.

Desc. tcr_reseller_id

TCR issued Reseller ID.

Desc. optout_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. tcr_csp_id

The Campaign Service Provider ID.

Typically in the form of SNNNNNN.

Desc. help_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. expedite_tier

Request that the campaign's provisioning be expedited with upstream.

• NONE - the default, no expedite, campaign will be processed at its normal rate

Desc. optin_keywords

Must be a CSV, that is a comma separated list of keywords.

Excess spaces will be trimmed around each keyword.

Desc. terms_and_conditions

Do you accept TCR's Terms and Conditions, this flag MUST be true in order to register a campaign.

If false the campaign will not be accepted for registration.

Example

{
  "message_flow": "string",
  "tcr_campaign_id": "C000000",
  "help_message": "string",
  "embedded_phone": false,
  "tcr_brand_id": "B000000",
  "embedded_link": false,
  "tcr_reseller_id": "R000000",
  "age_gated": false,
  "vertical": "TECHNOLOGY",
  "optout_message": "string",
  "description": "string",
  "auto_renewal": true,
  "embedded_link_sample": "string",
  "optout_keywords": "OPTOUT,STOP,UNSUBSCRIBE",
  "terms_and_conditions_link": "string",
  "direct_lending": false,
  "sub_use_cases": [
    "string"
  ],
  "optin_message": "string",
  "mno_ids": [
    "string"
  ],
  "reseller_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "subscriber_optout": false,
  "brand_id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "use_case": "string",
  "tcr_csp_id": "S000000",
  "subscriber_optin": false,
  "help_keywords": "HELP,INFO",
  "expedite_tier": "NONE",
  "affiliate_marketing": false,
  "subscriber_help": false,
  "samples": [
    "string"
  ],
  "optin_keywords": "OPTIN,START,SUBSCRIBE",
  "privacy_policy_link": "string",
  "number_pool": false,
  "terms_and_conditions": false
}

Unregister Campaign

Parameters

Request for unregistering a TCR Campaign.

Type Object

Example

{
  "campaign_id": "89900e23-aafc-4b03-954d-0b11d3948042",
  "tcr_campaign_id": "B000000"
}

TCR Campaign

Before any numbers can be added to a campaign, the campaign must be either created by Tychron, or be shared by a valid CSP with Tychron and approved.

Please contact Tychron Support on the setup process for campaign sharing before attempting to provision any numbers with campaigns.

If there are existing campaigns (see GET /api/v1/campaigns), you can provision numbers under a campaign, if it has been dca_approved.

Add Campaign Numbers

Numbers can be added to an existing campaign with with a ADD_CAMPAIGN_NUMBERS request.

Parameters

Request for register numbers under campaign

Type Object

Desc. campaign_id

The internal UUID of a known campaign.

• This field will be backfilled if tcr_campaign_id is provided instead.
• If this field AND tcr_campaign_id are provided they must resolve to the same campaign.

Desc. numbers

A list of NANP 11-digit numbers to add campaigns to.

Keep in mind, campaigns are only supported on non-tollfree TenDLC numbers.

For example: 12003004000.

Desc. tcr_campaign_id

The TCR issued Campaign ID, typically in the form of CNNNNNN.

• This field will be backfilled if campaign_id is provided instead.
• If this field AND campaign_id are provided they must resolve to the same campaign.

Desc. tmobile_enabled

Whether or not this request is subject to additional T-Mobile enablement, this will be auto-populated during request processing.

Note that this is based on a campaign's supported MNOs.

Example

{
  "campaign_id": "5b502159-a3f4-48bd-87e7-205b7f0d6c7f",
  "numbers": [
    "12003004000"
  ],
  "tcr_campaign_id": "C000000",
  "tmobile_enabled": true
}

Remove Campaign Numbers

Numbers can be removed from their campaign with a REMOVE_CAMPAIGN_NUMBERS request.

Parameters

Request for detaching numbers from their known campaign.

Type Object

Desc. numbers

A list of NANP 11-digit numbers to disable messaging for

Example

{
  "numbers": [
    "12003004000"
  ]
}