How to Register a Sender ID Using APIs with AWS End User Messaging

Introduction

Welcome to our comprehensive guide on using the AWS End User Messaging V2 APIs to obtain a Sender ID in countries that require registration. Sender ID registration is a crucial step for businesses looking to establish a trusted communication channel with their customers via SMS. In countries such as Jordan, the Philippines, Qatar, and others registering a Sender ID is mandatory to ensure compliance with local regulations and to enhance message deliverability. You can view a list of countries that support Sender ID and require registration here.

NOTE: This post is specific to Sender IDs, to learn more about choosing the right originator for your use case read this post on How to Send SMS Globally Using AWS End User Messaging.

This guide will walk you through the high-level process of creating and submitting a Sender ID registration using AWS End User Messaging V2 APIs. While we will use Jordan as a case study in this post, the principles and steps outlined here apply to other countries with similar registration requirements for Sender ID.

High-Level Understanding of the Registration APIs

To successfully register a Sender ID, you’ll need to interact with several AWS End User Messaging APIs. Here’s a brief overview of the key APIs involved and their roles in the registration process:

1. DescribeRegistrationTypeDefinitions

• Purpose: Retrieves the specified registration type definitions.
• Use Case: View the requirements for creating, filling out, and submitting each registration type.
• Key Point: Each country has a specific “RegistrationType” that needs to be used in the next step to create a registration.
• Documentation: DescribeRegistrationTypeDefinitions

2. CreateRegistration

• Purpose: Creates a new registration “container”. This is an empty registration that we are going to fill with our data in later steps.
• Key Field: RegistrationType
  • Controls the type of registration (e.g., Toll-Free, 10DLC, JO_SENDER_ID_REGISTRATION, etc.).
• Documentation: CreateRegistration

3. DescribeRegistrationFieldDefinitions

• Purpose: Retrieves the specified RegistrationType field definitions.
• Use Case: View the requirements for creating, filling out, and submitting each registration type. There are different field types (SELECT, TEXT, ATTACHMENT) dependent on the type of data required to register as well as the actual questions that need to be answered.
• Documentation: DescribeRegistrationFieldDefinitions

4. CreateRegistrationAttachment

• Purpose: Uploads additional documentation that some countries require. Not all countries require documentation that needs to be uploaded so this may be an optional step depending on the country you are registering for. We will be registering for Jordan in this example which does require us to upload a document to complete the registration.
• Key Field: RegistrationAttachmentId
  • Used in the next action to include an attachment in the registration when you are required to provide one. Not all registration types require an attachment.
• File Specifications:
  • Maximum file size: 500kb
  • Valid file extensions: PDF, JPEG, or PNG
• Documentation: CreateRegistrationAttachment

5. PutRegistrationFieldValue

• Purpose: Sets the value for a specific registration field.
  • This action needs to be repeated for all required fields.
• Documentation: PutRegistrationFieldValue

6. SubmitRegistrationVersion

• Purpose: Submits the specified registration version for review and approval. You are able to create new versions of the registration using CreateRegistrationVersion so make sure if you created another Registration Version that you use the correct ID.
• Important Notes:
  • Ensure that you are using the correct Version if you created multiple
  • Ensure all data is correct before submission.
  • Initial status will be “CREATED” and should change to “REVIEWING” within 24 hours.
  • You cannot edit or delete the registration until it is approved or rejected.
• Documentation: SubmitRegistrationVersion

Detailed Steps for Sender ID Registration in Jordan

In the following sections, we’ll dive deeper into each of these steps, providing more detail on the API calls and responses as well as best practices to ensure a smooth registration process. Whether you’re registering in Jordan or another country with similar requirements, this guide will equip you with the knowledge you need to successfully register a Sender ID.

Step 1: DescribeRegistrationTypeDefinitions

The first step is to run DescribeRegistrationTypeDefinitions to retrieve all specified registration type definitions. This API provides a detailed response that includes various attributes related to the registration process. Let’s break down these attributes for Jordan:

• Country: JO
  • Description: Specifies the country code for which the registration type definitions are being described. JO stands for Jordan.
  • Implication: Understanding the country code is crucial because registration requirements and processes can vary significantly from one country to another.
• ResourceType: SENDER_ID
  • Description: Indicates the type of resource for which the registration is being defined.
  • Implication: Knowing that the resource type is SENDER_ID helps you understand that the registration process is focused on obtaining approval specifically for a Sender ID as there are some countries that have multiple registration types.
• Registration Type: JO_SENDER_ID_REGISTRATION
  • Description: Specifies the exact type of registration required for the given country and resource type.
  • Implication: This registration type is critical because it dictates the specific steps, documentation, and criteria you need to meet to successfully register a Sender ID in Jordan.
  • You will use this value to create the initial registration
• Association Behavior: ASSOCIATE_ON_APPROVAL
  • Description: Describes how the registered Sender ID will be associated with your AWS account once the registration is approved.
  • Implication: ASSOCIATE_ON_APPROVAL means that the Sender ID will be automatically associated with your account as soon as the registration is approved, simplifying the process post-approval. There will be nothing more for you to do once you have successfully submitted your registration and it has been approved. Some registration types require steps to be taken after the registration is approved, this is not one of them.
• Disassociation Behavior: DISASSOCIATE_ALL_CLOSES_REGISTRATION
  • Description: Explains what happens when you disassociate the Sender ID from your account.
  • Implication: This behavior is important to note because it means that the origination identity must be disassociated from the registration before the registration can be closed.

Step 2: CreateRegistration

Next, use CreateRegistration with the RegistrationType for Jordan, “JO_SENDER_ID_REGISTRATION,” to generate a blank registration “container” for a Jordan Sender ID. Make sure to log the “RegistrationId” for later use as it will be used throughout the rest of the process.

Below is a screenshot of the registration that was created in the console

Step 3: DescribeRegistrationFieldDefinitions

Use DescribeRegistrationFieldDefinitions with “JO_SENDER_ID_REGISTRATION” as the RegistrationType to pull down all the fields that need to be filled out to submit the registration.

Important Field Attributes

• FieldPath
  • Value: A string that specifies the path to the field within the registration form (e.g., companyInfo.companyName).
  • Description: The FieldPath attribute provides a hierarchical path to the specific field within the registration form. It identifies one of the fields we will use later to input the data into our registration
  • Implication: Ensures that you place the required information in the correct field, essential for accurate processing.
• FieldRequirement
  • Value: Indicates whether the field is required, optional, or conditional (REQUIRED, OPTIONAL, CONDITIONAL).
  • Description: The FieldRequirement attribute specifies the necessity of the field in the registration process. A REQUIRED field must be filled out for the registration to be submitted, while an OPTIONAL field can be left blank if not applicable. A CONDITIONAL field depends on other fields and may become required based on certain conditions.
  • Implication: Helps prioritize which fields to complete and ensures critical information is not missed.
• FieldType
  • Value: Describes the type of data expected in the field (SELECT, TEXT, ATTACHMENT).
  • Description: Indicates the format and type of data that should be entered into the field.
  • Implication: Ensures the registration form is valid and reduces the risk of errors or rejections due to incorrect data formats.

See the categories of the Jordan registration in the screenshot below

Let’s break down the required fields that are common across all Sender Id registrations and their descriptions in a more readable format:

Sender ID Information:

1. Sender ID (Required)
   1. Must be 3-11 alphanumeric characters
   2. Must contain at least one letter
   3. Example: “EXAMPLE”
2. Sender ID Description (Optional)
   1. Explain the connection between company name and sender ID
   2. Max 500 characters
3. Proof of Sender ID Connection (Optional)
   1. Required only if the connection between company name and sender ID isn’t obvious
   2. Must provide evidence of intellectual property rights

Below is a screenshot of the Console version

Company Information:

1. Company Name (Required)
   1. Legal company name
   2. Max 100 characters
   3. Example: “Example Corp”
2. Company ID (Required)
   1. Legal identification number (EIN/VAT)
   2. Alphanumeric only
   3. Max 30 characters
3. DBA Name (Optional)
   1. “Doing Business As” name if different from legal name
   2. Max 100 characters
4. Website (Required)
   1. Company’s full URL
   2. Example: “http://www.example.com”
5. Area of Business (Required)
   1. Choose one: Agriculture, Communication, Construction, Education, Energy, Entertainment, Financial, Government, Healthcare, Hospitality, Insurance, Manufacturing, Real estate, Retail, Technology, Other

Below is a screenshot of the Console version

Company Address:

1. Address Line 1 (Required)
2. Address Line 2 (Optional)
3. City (Required)
4. State/Province (Optional)
5. Postal Code (Optional)
6. Country Code (Required)
   1. Two-letter ISO code
   2. Example: “US”

Below is a screenshot of the Console version

Contact Information:

1. Email Address (Required)
   1. Valid email format
   2. Example: “janedoe@example.com “
2. Phone Number (Required)
   1. Must contain at least 3 digits
   2. Example: “+12065550100“

Below is a screenshot of the Console version

Messaging Use Case:

1. Use Case Category (Required)
   1. Choose one: One-time passcodes, Account/security alerts, Purchase/delivery notifications, Public service announcements, Polling/surveys, Info on demand, Other
2. Use Case Description (Required)
   1. Max 500 characters
3. Monthly Message Volume (Required)
   1. Choose one: 10, 100, 1,000, 10,000, 100,000, 1,000,000, 10,000,000+
4. Opt-in Description (Required)
   1. How users will opt-in to receiving messages
   2. Max 500 characters

Below is a screenshot of the Console version

Message Samples:

1. Message Sample 1 (Required)
   1. Max 306 characters
2. Message Sample 2 (Optional)
   1. Max 306 characters
3. Message Sample 3 (Optional)
   1. Max 306 characters

Below is a screenshot of the Console version

Jordan-Specific Requirements

Some countries, not all, also have country-specific requirements. Jordan requires the following for this registration:

1. Company Registration Documentation (Required)
   1. Must provide company registration docs (both local and international companies)
   2. This is an Attachment type so we will need to use “CreateRegistrationAttachment” first in order to put this value into the registration. We will cover this further down in the process
2. Transactional Acknowledgement (Required)
   1. Must acknowledge that only transactional messages will be sent
   2. Promotional content is not allowed
   3. This is a “Select” field type with the only option being “Yes” meaning you will be unable to register unless you agree to this acknowledgement

Below is a screenshot of the Console version

Step 4: CreateRegistrationAttachment

Now that you know all the fields required for the Jordan Sender ID registration, you need to gather all the necessary data, including the required attachment. The Jordan Sender ID registration requires only one attachment. Let’s review how to add this attachment to your registration.

To add an attachment to your registration, use the CreateRegistrationAttachment API. You have two options for providing this document:

1. Specify a file in S3:
   1. Ensure you use Standard buckets, S3 Express is not supported.
2. Upload it as a Base64-encoded binary data object:
   1. This method allows you to directly upload the document without needing to store it in S3 first.

Important: After successfully running the CreateRegistrationAttachment command, you will receive a “RegistrationAttachmentId.” Make sure to log this ID, as you will need it to attach the upload to your registration.

Step 5: PutRegistrationFieldValue

Use PutRegistrationFieldValue to input data into each field. Loop through each input as each call only inputs a single value. Specify the “RegistrationId” logged earlier when making each call. Your options for field values are:

• RegistrationAttachmentId: The unique identifier for the registration attachment
• SelectChoices: An array of values for the form field that were specified in the payload earlier
• TextValue: The text data for a free form field

Step 6: Review your registration

Once you have successfully inputted all the values for your registration, you can review your inputs in one of two ways:

1. View in the Console:
   1. Your registration details are accessible directly in the AWS Management Console.
2. Use DescribeRegistrationFieldValues:
   1. You can pull down your registration and review each of its values using the DescribeRegistrationFieldValues API. Make sure to use the right version ID of your registration.

Step 7: Submitting Your Registration

Once all values in your registration are complete and correct, submit your registration for review using the SubmitRegistrationVersion API. Provide your “RegistrationId” when making this call.

Initial Status:

• The initial status of your registration will be “CREATED.”
• It should change to “REVIEWING” within 24 hours.
• If the status does not change from “CREATED” to “REVIEWING” within 24 hours and you’ve confirmed you SUBMITTED your registration version, create a support case for assistance.

Sender ID Registration Review Process

Each country has its own review process and timeline. Each registration is examined on a first-in/first-out basis by the registrar for each country. AWS does not review your registrations so make sure that you are completing this registration with this in mind. There are humans reviewing these registrations that do not know your company or your use case so make sure to be clear and concise in your responses.

If the registrar is confused by your submission, they may reject it, and you will need to start the process over, amending the registration where necessary and resubmitting. This puts you in the back of the line again, which will increase your timeline.

Conclusion

Completing a Sender ID registration using the End User Messaging V2 APIs involves several steps, each critical to ensuring compliance and successful registration. By following this guide, you can navigate the process efficiently, from understanding the required fields to submitting your registration for review. Whether you’re registering in Jordan or another country with different requirements, this guide provides the knowledge and steps needed to successfully obtain a Sender ID and establish a trusted communication channel with your customers via SMS.