Register an alphanumeric sender ID
Registering for an alphanumeric sender ID consists of the following steps:
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. |
Get Market Requirements
The /markets/details endpoint provides information on the general configuration of a market and the various policies that apply, depending on specific market regulations.
The following cURL command demonstrates how to retrieve the configuration for registering an alphanumeric sender ID in Australia:
curl --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/markets/details?marketCode=AU' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'Response:
{
"marketVersions": [
{
"id": <marketVersionId>,
"marketCode": "AU",
"registrationType": "ALPHANUMERIC_SENDER_ID",
"specialConditions": {
"prompt": "Are you the brand owner of the sender ID to be registered?",
"chainedSpecialConditions": [
{
"policyId": <policyId_Aggregator>,
"answer": "No",
"chainedSpecialConditions": []
},
{
"policyId": <policyId_BrandOwner>,
"answer": "Yes",
"chainedSpecialConditions": []
}
]
},
"status": "ACTIVE",
"majorVersion": 8,
"minorVersion": 0,
"createTime": "2024-09-12T10:45:30.594765Z"
}
],
"totalSize": 1,
"nextPageToken": ""
}The response contains the specialConditions object, and for this market there are two different policies depending on the type of customer: aggregator or brand owner. Let's consider for this guide that the customer is an aggregator.
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.
curl --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/policies/<policyId_Aggregator>' \
--header 'Authorization: ••••••'Response:
{
"id": <policyId_Aggregator>,
"jsonPolicy": {
"senderIdTemplate": {
"properties": [
{
"description": "From 3 to 11 characters.\n You can use upper/lower-case letters, numbers, spaces, hyphens, underscores, and periods.",
"maxLength": 11,
"messages": {
"maxLength": "Alphanumeric Sender ID should NOT be longer than 11 characters",
"minLength": "Alphanumeric Sender ID should NOT be shorter than 3 characters",
"pattern": "Cannot contain any special characters."
},
"minLength": 3,
"name": "senderId",
"pattern": "^[A-Za-z0-9 \\-_\\.]*[A-Za-z0-9-_\\.][A-Za-z0-9 \\-_\\.]*$",
"required": true,
"title": "Alphanumeric Sender ID",
"type": "string"
},
{
"items": {
"enum": [
"One Time Password",
"Transactional",
"Internal communication",
"Content delivery",
"Conversational",
"Marketing"
],
"type": "string"
},
"messages": {
"minItems": "You need to select at least one purpose for your traffic."
},
"minItems": 1,
"name": "trafficPurpose",
"required": true,
"title": "Purpose of the traffic",
"type": "array",
"uniqueItems": true
},
{
"description": "",
"enum": [
null,
true
],
"name": "authorized",
"required": true,
"title": "We are authorized to use the sender ID on behalf of a third-party sender with a valid use case.",
"type": "boolean"
}
]
},
"contactPersonTemplate": null,
"companyDetailsTemplate": {
"properties": [
{
"description": "Test",
"maxLength": 50,
"messages": {
"maxLength": "Company name should NOT be longer than 50 characters",
"minLength": "Company name should NOT be shorter than 1 characters"
},
"minLength": 1,
"multiline": false,
"name": "companyName",
"pattern": ".",
"required": true,
"title": "Company name",
"type": "string"
},
{
"messages": {
"minLength": "At least 1 character is required",
"pattern": "Needs to be a valid website address"
},
"minLength": 1,
"name": "website",
"pattern": "^(http:\/\/www\\.|https:\/\/www\\.|http:\/\/|https:\/\/)?[a-z0-9]+([\\-\\.]{1}[a-z0-9]+)*\\.[a-z]{2,63}(:[0-9]{1,5})?(\/.*)?$",
"required": true,
"title": "Website",
"type": "string"
}
]
}
},
"attachments": [
{
"id": <attachmentId>,
"title": "Bulk List",
"description": "",
"mandatory": false,
"template": false
}
],
"fees": false,
"policyMultiType": "MULTI_SENDER",
"policyStatus": "ENABLED",
"statusDisclaimer": "",
"price": {
"mode": "NONE",
"subscription": null
}
}The jsonPolicy object contains the form template of the policy:
| Field | Description |
| senderIdTemplate | Contains the related senderId configuration. |
| contactPersonTemplate | Includes contact details like email, mobile phone, etc. |
| companyDetailsTemplate | Includes the information necessary from the company brand. |
Each property has a set of fields. Please find the specification of each field in the API documentation.
Attachments block includes all the files that must be added to the registration, if template is true, a template for this attachment can be downloaded (see API documentation for the downloadTemplate endpoint).
policyMultiType specifies the number of sender IDs allowed per registration, where SINGLE means 1 and MULTI_SENDER up to 50 sender Ids.
Price section includes the billing fees associated with this policy, per sender ID.
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, while contactPersonTemplate and companyDetailsTemplate must be included in additionalDetails.
In this example, the request is for two sender IDs in Australia, as an aggregator: AUST01 and AUST02:
curl -XPOST --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/registrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"callbackUrl": "",
"notificationContacts": [
"john.doe@mycmmompany.us"
],
"policyId": <policyId_Aggregator>,
"requestDetails": [
{
"additionalDetails": [{
"companyName": "Customer Company Name",
"website": "www.customer-website.com"
}],
"senderIdDetails": [
{
"senderId": "AUST01",
"trafficPurpose": ["Transactional"],
"authorized": true
},
{
"senderId": "AUST02",
"trafficPurpose": ["One Time Password", "Transactional"],
"authorized": true
}
]
}
],
"tags": [
"#mytag",
"#tag2"
]
}
'Response:
{
"id": <registrationId>,
"policyId": <policyId_Aggregator>,
"status": "IN_QUEUE",
"tags": [
"#mytag",
"#tag2"
],
"etaDate": "",
"createTime": "2024-11-12T13:52:15",
"updateTime": "2024-11-12T13:52:15",
"owner": "Public API",
"notificationContacts": [
"john.doe@mycmmompany.us"
],
"requestDetails": [
{
"senderIdDetails": [
{
"senderId": "AUST01",
"trafficPurpose": [
"Transactional"
],
"authorized": true
},
{
"senderId": "AUST02",
"trafficPurpose": [
"One Time Password",
"Transactional"
],
"authorized": true
}
],
"additionalDetails": [
{
"companyName": "Customer Company Name",
"website": "www.customer-website.com"
}
]
}
],
"attachments": [],
"logs": [
{
"message": "",
"registrationState": "DRAFT",
"createTime": "2024-11-12T13:52:15"
},
{
"message": "",
"registrationState": "IN_QUEUE",
"createTime": "2024-11-12T13:52:15"
}
],
"callbackUrl": "",
"price": {
"currency": "",
"frequency": 0,
"recurrentFeeAmount": "",
"setupFeeAmount": "",
"mode": "NONE"
},
"registrationType": "ALPHANUMERIC_SENDER_ID"
}Upload an attachment
Once the registration is created, an attachment can be uploaded:
curl -XPOST --location 'https://senderid.registrations.api.sinch.com/v1/projects/<projectId>/registrations/<registrationId>/attachments/<attachmentId>' \
--header 'Authorization: ••••••' \
--form 'file=@"<file_location>"'
