Introduction

Welcome to the Corelink Telecom API! You can use our API to access REST endpoints, which provide an access to the Corelink Telecom Platform.

The platform host name can be different based on your project settings. In this documentation it's assumed your project belongs to the us1 zone.

Authentication

To authorize, use this code:

curl 'https://us1-api.corelinktelecom.com' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

Make sure to replace YOUR_API_TOKEN with your API token and YOUR_PROJECT_ID with your project ID.

You can obtain Corelink Telecom API token and your project ID at the Developer Dashboard. All requests should use application/json content type.

The platform expects for the API token and project ID to be included in all API requests to the server in a header that looks like the following:

x-api-token: YOUR_API_TOKEN
x-project-id: YOUR_PROJECT_ID

You must replace YOUR_API_TOKEN with your personal API token and YOUR_PROJECT_ID with your project ID.

Messaging API

Send a Message

curl --request POST 'https://us1-api.corelinktelecom.com/v1/messages' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "from": "+1234567890",
    "to": ["+15678901234", "+15678901256"],
    "body": "text of the message",
    "mediaURLs": ["http://example.com/image1.png", "http://example.com/image2.png"]
}'

The above command returns HTTP Code 201 and JSON structured like this:

{
    "messageId": "d52ea401-c1f4-4cfd-b8b4-68932ffcb6c5"
}

This endpoint sends a message (SMS/MMS) in a synchronous way: it will wait until all necessary media is uploaded and a message is delivered to the mobile network operator (MNO).

HTTP Request

POST https://us1-api.corelinktelecom.com/v1/messages

Request Body Parameters

Parameter	Type	Required?	Description
from	String	true	The phone number the message is being sent from. The number should be in E.164 format.
to	String[]	true	The array of phone numbers the message is being sent to. Each number should be in E.164 format.
body	String	false	The body of the message. Can be omitted if `mediaURLs` array is not empty.
mediaURLs	String[]	false	The array of http links to the media attached. In case of non-empty value the message is automatically being sent as `MMS`.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 201 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
messageId	String	The ID of the sent message. This ID can be used to fetch the details about the message.

Get Messages

curl --request GET 'https://us1-api.corelinktelecom.com/v1/messages' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

The above command returns HTTP Code 200 and JSON structured like this:

{
    "messages": [
        {
            "messageId": "992ba321-f230-4c90-a420-95536b06e454",
            "from": "+1234567890",
            "to": ["+15678901234", "+15678901256"],
            "body": "text of the message",
            "messageType": "mms",
            "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
            "direction": "outbound",
            "segments": 1,
            "mediaURLs": ["http://example.com/image1.png", "http://example.com/image2.png"],
            "isDeliveryReceipt": false,
            "sentDateTime": "2022-09-26T20:25:35.152Z"
        },
        {
            "messageId": "779d87a1-1b08-461f-81f6-7c172f382fa0",
            "from": "+15678901234",
            "to": "+1234567890",
            "body": "sms text",
            "messageType": "sms",
            "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
            "direction": "inbound",
            "segments": 1,
            "mediaURLs": [],
            "isDeliveryReceipt": false,
            "sentDateTime": "2022-09-26T21:24:35.153Z"
        },
    ],
    "totalCount": 2
}

This endpoint retrieves the list of all messages in the project sorted by sentDateTime descending.

HTTP Request

GET https://us1-api.corelinktelecom.com/v1/messages

Query String Parameters

Parameter	Description
limit	Indicates the maximum amount of messages to return.
offset	How many messages to skip.
from	Filter messages by the `from` property.
to	Filter messages by the `to` property.
sentDateTimeFrom	Fetch messages sent after `sentDateTimeFrom`. The date should be in the ISO_8601 format.
sentDateTimeTo	Fetch messages sent before `sentDateTimeTo`. The date should be in the ISO_8601 format.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 200 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
messages	Message[]	Array of messages. The `Message` data model is described here.
totalCount	Numeric	Total amount of messages.

Get a Specific Message

curl --request GET 'https://us1-api.corelinktelecom.com/v1/messages/992ba321-f230-4c90-a420-95536b06e454' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

The above command returns HTTP Code 200 and JSON structured like this:

{
    "message": {
        "messageId": "992ba321-f230-4c90-a420-95536b06e454",
        "from": "+1234567890",
        "to": ["+15678901234"],
        "body": "text of the message",
        "messageType": "mms",
        "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
        "direction": "outbound",
        "segments": 1,
        "mediaURLs": ["http://example.com/image1.png", "http://example.com/image2.png"],
        "isDeliveryReceipt": false,
        "sentDateTime": "2022-09-26T20:25:35.152Z"
    }
}

This endpoint retrieves a specific message in the project by messageId.

HTTP Request

GET https://us1-api.corelinktelecom.com/v1/messages/<messageId>

Query String Parameters

Parameter	Description
messageId	Unique ID of the message

HTTP Response Code

A successful operation an HTTP response will have the HTTP 200 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
message	Message	Fetched message. The `Message` data model is described here.

Incoming Message Webhook

POST request to a user-defined URL

The webhook JSON structure looks like this:

{
    "message": {
        "messageId": "992ba321-f230-4c90-a420-95536b06e454",
        "from": "+1234567890",
        "to": ["+15678901234"],
        "body": "text of the message",
        "messageType": "mms",
        "mediaURLs": ["http://example.com/image1.png", "http://example.com/image2.png"],
        "isDeliveryReceipt": false,
        "sentDateTime": "2022-09-26T20:25:35.152Z"
    }
}

The incoming message webhook is an HTTP POST request to a user-defined URL. This request is being executed for each inbound message.

HTTP Request

POST <user_defined_URL>

HTTP Response Code

The webhook request expects an HTTP 200 or HTTP 201 response.

Webhook Request Body

Parameter	Type	Description
message	InboundMessage	The inbound message. The `InboundMessage` data model is described here.

Numbers API

Search Inventory

curl --request POST 'https://us1-api.corelinktelecom.com/v1/numbers/search' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "telephoneNumberType": "local",
    "maxResults": 10,
    "lata": "730",
    "countryCode": "US",
    "regionName": "CA",
    "locationName": "Los Angeles"
}'

The above command returns HTTP Code 200 and JSON structured like this:

{
    "telephoneNumbers": [
        {
            "telephoneNumber": "+1234567890",
            "telephoneNumberType": "local",
            "locationName": "Los Angeles",
            "lata": "730",
            "countryCode": "US",
            "regionName": "CA",
            "capabilities" : {
              "cnam": true,
              "e911": true,
              "sms": true,
              "mms": true
            }
        },
        {
            "telephoneNumber": "+1234560987",
            "telephoneNumberType": "local",
            "locationName": "Los Angeles",
            "lata": "730",
            "countryCode": "US",
            "regionName": "CA",
            "capabilities" : {
              "cnam": true,
              "e911": true,
              "sms": true,
              "mms": true
            }
        },
    ],
    "totalCount": 2
}

This endpoint searches telephone numbers filtering by an applied criteria.

HTTP Request

POST https://us1-api.corelinktelecom.com/v1/numbers/search

Request Body Parameters

Parameter	Type	Required?	Description
telephoneNumberType	String	false	Telephone number type to search. Possible values are `local`,`toll-free` and `short`. Default value is `toll-free`.
maxResults	Numeric	true	Maximum amount of phone numbers to return.
lata	String	false	LATA to filter phone numbers.
countryCode	String	false	Country to filter phone numbers.
regionName	String	false	State to filter phone numbers. The value should be 2-letter and 2-digit codes from the ANSI standard.
locationName	String	false	Name of the city to filter phone numbers.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 200 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
telephoneNumbers	TelephoneNumberInventoryInfo[]	Array of telephone numbers. The `TelephoneNumberInventoryInfo` data model is described here.
totalCount	Numeric	Total amount of found phone numbers.

Purchase a Phone Number

curl --request POST 'https://us1-api.corelinktelecom.com/v1/numbers' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "telephoneNumber": "+1234567890",
    "note": "this is a note for the phone number",
    "incomingMessageWebHook": {
      "url": "http://example.com",
      "headers": ["header1": "value1", "header2": "value2"],
    }
}'

The above command returns HTTP Code 201 and JSON structured like this:

{
    "telephoneNumberId": "1706b9c6-7f76-47f2-b09f-0175d4bdc8fb"
}

This endpoint purchases a phone number.

HTTP Request

POST https://us1-api.corelinktelecom.com/v1/numbers

Request Body Parameters

Parameter	Type	Required?	Description
telephoneNumber	String	true	The phone number to purchase. The number should be in E.164 format.
note	String	false	The custom note for the telephone number.
incomingMessageWebHook	WebHook	false	The definition of the incoming message webhook. In case of an empty value a global project-wise webhook will be used instead. The `WebHook` data model is described here.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 201 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
telephoneNumberId	String	The ID of the purchased telephone number. This ID can be used to fetch the details about the telephone number.

Get Purchased Phone Numbers

curl --request GET 'https://us1-api.corelinktelecom.com/v1/numbers' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

The above command returns HTTP Code 200 and JSON structured like this:

{
    "telephoneNumbers": [
        {
            "telephoneNumberId": "e559d98c-0204-4ed2-a09f-c7c35c089e37",
            "telephoneNumber": "+12029494877",
            "telephoneNumberType": "local",
            "note": "some note",
            "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
            "incomingMessageWebHook": null,
            "locationName": "DALLAS",
            "lata": "552",
            "regionName": "TX",
            "countryCode": "1",
            "capabilities": {
                "cnam": true,
                "e911": true,
                "sms": true,
                "mms": true
            },
            "purchaseDateTime": "2022-10-26T20:25:35.152Z"
        },
        {
            "telephoneNumberId": "b2f2c734-0606-4fa5-a5e9-66dc9c20b057",
            "telephoneNumber": "+18009494877",
            "telephoneNumberType": "toll-free",
            "note": null,
            "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
            "incomingMessageWebHook": null,
            "locationName": null,
            "lata": null,
            "regionName": null,
            "countryCode": null,
            "capabilities": {
                "cnam": false,
                "e911": false,
                "sms": true,
                "mms": false
            },
            "purchaseDateTime": "2022-10-27T20:25:35.152Z"
        }
    ],
    "totalCount": 5
}

This endpoint retrieves the list of all purchased phone numbers in the project sorted by purchaseDateTime descending.

HTTP Request

GET https://us1-api.corelinktelecom.com/v1/numbers

Query String Parameters

Parameter	Description
limit	Indicates the maximum amount of phone numbers to return.
offset	How many phone numbers to skip.
telephoneNumberFilter	Filter telephone numbers by the `telephoneNumber` property.
noteFilter	Filter telephone numbers by the `note` property.
purchaseDateTimeFrom	Fetch phone numbers purchased after `purchaseDateTimeFrom`. The date should be in the ISO_8601 format.
purchaseDateTimeTo	Fetch phone numbers purchased before `purchaseDateTimeTo`. The date should be in the ISO_8601 format.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 200 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
telephoneNumbers	TelephoneNumber[]	Array of telephone numbers. The `TelephoneNumber` data model is described here.
totalCount	Numeric	Total amount of telephone numbers.

Get a Purchased Phone Number

curl --request GET 'https://us1-api.corelinktelecom.com/v1/numbers/e559d98c-0204-4ed2-a09f-c7c35c089e37' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

The above command returns HTTP Code 200 and JSON structured like this:

{
    "telephoneNumber": {
        "telephoneNumberId": "e559d98c-0204-4ed2-a09f-c7c35c089e37",
        "telephoneNumber": "+12029494877",
        "telephoneNumberType": "local",
        "note": "some note",
        "projectId": "88a83eb2-4abb-4e21-8304-57d666510616",
        "incomingMessageWebHook": null,
        "locationName": "DALLAS",
        "lata": "552",
        "regionName": "TX",
        "countryCode": "1",
        "capabilities": {
            "cnam": true,
            "e911": true,
            "sms": true,
            "mms": true
        },
        "purchaseDateTime": "2022-10-26T20:25:35.152Z"
    }
}

This endpoint retrieves a purchased phone number in the project by telephoneNumberId.

HTTP Request

GET https://us1-api.corelinktelecom.com/v1/numbers/<telephoneNumberId>

Query String Parameters

Parameter	Description
telephoneNumberId	Unique ID of the phone number.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 200 code. In case of an error the API will return one of the error http codes described here.

Response Body

Parameter	Type	Description
telephoneNumber	TelephoneNumber	Fetched telephone number. The `TelephoneNumber` data model is described here.

Release a Phone Number

curl --request DELETE 'https://us1-api.corelinktelecom.com/v1/numbers/e559d98c-0204-4ed2-a09f-c7c35c089e37' \
  --header 'x-api-token: YOUR_API_TOKEN' \
  --header 'x-project-id: YOUR_PROJECT_ID' \
  --header 'Content-Type: application/json'

The above command returns HTTP Code 204 with an empty response body.

This endpoint releases a purchased phone number by telephoneNumberId.

HTTP Request

DELETE https://us1-api.corelinktelecom.com/v1/numbers/<telephoneNumberId>

Query String Parameters

Parameter	Description
telephoneNumberId	Unique ID of the phone number.

HTTP Response Code

A successful operation an HTTP response will have the HTTP 204 code. In case of an error the API will return one of the error http codes described here.

Response Body

The request returns an empty response body.

Data Models

Message

Property	Type	Description
messageId	String	Unique ID of the message.
from	String	Phone number the message was sent from. The value has E.164 format.
to	String[]	Array of phone numbers the message was sent to. Each phone number has E.164 format.
body	String	Text of the message. It can be empty in case `mediaURLs` has non-zero length.
messageType	String	Type of the message. Possible values are: `sms`, `mms`.
projectId	String	ID of the project the message belongs to.
direction	String	Direction of the message. Possible values are: `outbound`, `inbound`.
segments	Numeric	Amount of segments the message was split into.
isDeliveryReceipt	Boolean	Indicates if the message is a delivery receipt.
sentDateTime	String	Date and time when the message was sent. The value has the ISO_8601 format.

Inbound Message

Property	Type	Description
messageId	String	Unique ID of the message.
from	String	Phone number the message was sent from. The value has E.164 format.
to	String[]	Array of phone numbers the message was sent to. Each phone number has E.164 format.
body	String	Text of the message. It can be empty in case `mediaURLs` has non-zero length.
messageType	String	Type of the message. Possible values are: `sms`, `mms`.
isDeliveryReceipt	Boolean	Indicates if the message is a delivery receipt.
sentDateTime	String	Date and time when the message was sent. The value has the ISO_8601 format.

Telephone Number Inventory Info

Property	Type	Description
telephoneNumber	String	Telephone number is E.164 format.
telephoneNumberType	String	Type of the telephone number. Possible values are `local`,`toll-free` and `short`.
cityName	String	City name the phone number belongs to.
lata	String	LATA
countryCode	String	Country the phone numbers belongs to.
stateCode	String	State code. The value has 2-letter and 2-digit codes from the ANSI standard.
capabilities	CapabilityInfo	Set of capabilities of the phone number (e.g. `sms`, `mms`)

Web Hook

Property	Type	Description
url	String	URL for the webhook.
headers	String[String]	The set of headers for the webhook. It is represented as a String->String map. Useful for specifying the `Authorization` header.

Telephone Number

Property	Type	Description
telephoneNumberId	String	Unique ID of the telephone number.
telephoneNumber	String	Telephone number is E.164 format.
telephoneNumberType	String	Type of the telephone number. Possible values are `local`,`toll-free` and `short`.
note	String	Custom note about the telephone number.
projectId	String	ID of the project the telephone number belongs to.
cityName	String	City name the phone number belongs to.
lata	String	LATA
countryCode	String	Country the phone numbers belongs to.
stateCode	String	State code. The value has 2-letter and 2-digit codes from the ANSI standard.
capabilities	CapabilityInfo	Set of capabilities of the phone number (e.g. `sms`, `mms`)
incomingMessageWebHook	WebHook	The definition of the incoming message webhook. In case of an empty value a global project-wise webhook will be used instead. The `WebHook` data model is described here.

Errors

The CoreLink API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.