Register a long number or short code sender ID

Registering for a long number or short code sender ID consists of the following steps:

Get market requirements
Get policy ID
Submit registration
Callback configuration

For all of the cURL commands below, the following variables must be filled using the access key credentials from your Sinch Customer Dashboard:

Variable	Description
`projectId`	Your project ID from your customer dashboard.
Authorization	Use either basic or OAuth 2.0 authorization.

Requesting a long number or short code is similar to requesting an alphanumeric, but in this case the senderId is not required, as this is assigned internally by Sinch.

Get Market Requirements

This is the same process as requesting an alphanumeric get Market Versions endpoint, but the registrationType query parameter must be specified to retrieve long number or short code markets.

In this example, the active market version for Australia and registration type long number are retrieved (both query parameters are optional, and the default registration type will be alphanumeric if the query parameters are not provided).

Copy

Copied

curl --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/markets/details?marketCode=AU&registrationType=LONG_NUMBER' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'

Response:

Copy

Copied

{
    "marketVersions": [
        {
            "id": <marketVersionId>,
            "marketCode": "AU",
            "registrationType": "LONG_NUMBER",
            "specialConditions": {
                "prompt": "Which type of number do you want?",
                "chainedSpecialConditions": [
                    {
                        "policyId": <policyId_Gold>,
                        "answer": "Gold",
                        "chainedSpecialConditions": []
                    },
                    {
                        "policyId": <policyId_Silver>,
                        "answer": "Silver",
                        "chainedSpecialConditions": []
                    },
                    {
                        "policyId": <policyId_Standard>,
                        "answer": "Standard",
                        "chainedSpecialConditions": []
                    }
                ]
            },
            "status": "ACTIVE",
            "majorVersion": 3,
            "minorVersion": 7,
            "createTime": "2024-11-21T11:18:00.809937Z"
        }
    ],
    "totalSize": 1,
    "nextPageToken": ""
}

Get Policy Id

Once the policyId is selected from the previous /markets/details endpoint, you must now make a call to the /policies/<policyId> endpoint to retrieve the policy related fields, configuration and attachments.

In this example policyId_Gold conditions are retrieved.

In some long number and short code policies, it is possible to request more than one number per registration; specify this number in the numbers property, which accepts up to 50 numbers per registration.

Copy

Copied

curl --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/policies/<policyId_Gold>' \
--header 'Authorization: ••••••'

Response:

Copy

Copied

{
    "id": <policyId_Gold>,
    "jsonPolicy": {
        "senderIdTemplate": {
            "properties": [
                {
                    "description": "If you need a two-way communication please provide the MO URL.",
                    "messages": {
                        "pattern": "Needs to be a valid website address"
                    },
                    "name": "mobileOriginatedURL",
                    "required": false,
                    "title": "Mobile Originated URL",
                    "type": "string"
                },
                {
                    "description": "How many Long Numbers would you like to request",
                    "multiline": false,
                    "name": "numbers",
                    "required": false,
                    "title": "Number Count",
                    "type": "string"
                }
            ]
        },
        "contactPersonTemplate": {
            "properties": [
                {
                    "description": "Please add an email account to contact you back",
                    "messages": {
                        "minLength": "Email Account should NOT be shorter than 1 characters",
                        "pattern": "Needs to be a valid email address"
                    },
                    "minLength": 1,
                    "multiline": false,
                    "name": "emailAccount",
                    "pattern": "^\\S+@\\S+\\.\\S+$",
                    "required": true,
                    "title": "Email Account",
                    "type": "string"
                }
            ]
        },
        "companyDetailsTemplate": null
    },
    "attachments": [],
    "fees": true,
    "policyMultiType": "SINGLE",
    "policyStatus": "ENABLED",
    "statusDisclaimer": "",
    "price": {
        "mode": "MANUAL",
        "subscription": null
    }
}

Submit Registration

With the information provided in the /policies endpoint, you can now create your alphanumeric registration.

senderIdTemplate properties must be added in an array (one object per sender ID included in the registration) in the senderIdDetails block.

In this example, we are requesting 10 Long Numbers in Australia.

Copy

Copied

curl -XPOST --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/registrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "callbackUrl": <callback_url>,
    "notificationContacts": [
        "john.doemycmmompany.us"
    ],
    "policyId": <policyId_Gold>,
    "requestDetails": [
        {
            "additionalDetails": [
                {
                    "emailAccount": "email@email.com"
                }
            ],
            "senderIdDetails": [{
                "mobileOriginatedURL": "https://www.mycompany.com/origin",
                "numbers": "10"
            }
            ]
        }
    ],
    "tags": [
        "#mytag",
        "#tag2"
    ]
}
'

Response:

Copy

Copied

{
    "id": <registration_id>,
    "policyId": <policyId_Gold>,
    "status": "PENDING_APPROVAL",
    "tags": [
        "#mytag",
        "#tag2"
    ],
    "etaDate": "",
    "createTime": "2024-11-27T09:49:46",
    "updateTime": "2024-11-27T09:49:47",
    "owner": "Public API",
    "notificationContacts": [
        "john.doemycmmompany.us"
    ],
    "requestDetails": [
        {
            "senderIdDetails": [
                {
                    "mobileOriginatedURL": "https://www.mycompany.com/origin",
                    "numbers": "10"
                }
            ],
            "additionalDetails": [
                {
                    "emailAccount": "email@email.com"
                }
            ]
        }
    ],
    "attachments": [],
    "logs": [
        {
            "message": "",
            "registrationState": "DRAFT",
            "createTime": "2024-11-27T09:49:46"
        },
        {
            "message": "",
            "registrationState": "PENDING_APPROVAL",
            "createTime": "2024-11-27T09:49:47"
        }
    ],
    "callbackUrl": <callback_url>,
    "price": {
        "currency": "",
        "frequency": 0,
        "recurrentFeeAmount": "",
        "setupFeeAmount": "",
        "mode": "MANUAL"
    },
    "registrationType": "LONG_NUMBER"
}

Callback Event Reception

If a callback URL was specified in the Submit Request endpoint, then callback events will be receives once the registration state changes.

In the example above the registration was marked as PENDING_APPROVAL, what means that prices are MANUAL and need to be reviewed manually by the customer's Account Manager. Once the registration is approved and it is moved to IN_QUEUE, a callback is sent to configured callback URL.

Please, read carefully the callback configuration API documentation to see how to authenticate this event.

Copy

Copied

{
  "eventId": <any_event_id>,
  "timestamp": "2024-11-27T09:56:02.805644815",
  "projectId": <projectId>,
  "resourceType": "LONG_NUMBER",
  "resourceId": <registration_id>,
  "eventType": "REGISTRATION_STATUS_CHANGE",
  "status": "IN_QUEUE"
}