Order new sender names - API Documentation

Use this method for bulk ordering new sender names.

POST https://a.loopmessage.com/api/v1/sender/new/

Before sending this request, you need to fetch plan_id from another API request.

To prevent billing issues, you can send this request once every 30 seconds.

Request body

This request has the same fields and validations as in a single request. The difference is that it needs to send these values as an array.

{
  "senders": [
    {
      "phone_region": "US",
      "plan_id": "string"
    },
    {
      "name": "sender2",
      "domain": "example.com",
      "plan_id": "string"
    }
  ]
}

Once the request is accepted, you will be automatically charged from the attached billing method

Order sender with a phone number

Name	Type	Description
plan_id*	String	Payment plan ID
phone_region*	String	Default value US. Possible values: US, GB, or AU*
zip_code	String	Optional. Only for US phone numbers.
sms_and_call	Bool	Optional.
forwarding_to_phone_number	String	Optional. Requires “sms_and_call”: true. Phone number region should support call forwarding.
whatsapp	Bool	Optional.
init_conversations	Bool	Optional. Enables the feature to send messages first.

*Important! Regions other than the US or GB require ID verification. For verification, you or your user needs a local ID, a local driver’s license, or an international passport. Once you order the sender name, you need to upload and assign an ID to your order. By local ID, it means if you need a phone number from Australia, you should have an Australian ID. In Europe, you need a European ID.

Use the document section to implement the flow with ID verification.

The sender activation process will begin only once the documents are assigned to the submission.

Contact

Name	Type	Description
first_name*	String	Displayed first name
last_name	String	Optional. Displayed last name
photo_url	String	Optional. The string must be a full URL of your photo. This must be a publicly accessible file URL: we will not be able to reach any URLs that are hidden or that require authentication. The photo must have a 1:1 aspect ratio (square).

// Example:
"senders" [{
 ...
 "contact": {
    "first_name": "John",
    "last_name": "Smith",
    "photo_url": "https://my.cdn.com/photo.png"
 }
}]

Port

Name	Type	Description
phone_number*	String	Phone number in international format. Eg: +13231111111
account_number*	String	Porting account number
pin*	String	Porting pin
carrier*	String	eg: Twilio

// Example:
"senders" [{
  ...
  "port": {
    "phone_number": "+13231111111",
    "account_number": "123456",
    "pin": "1234",
    "carrier": "Twilio"
  }
}]

Response example

{
    "count": 1,
    "items": [
        {
            "id": "f41c27d2-1251-488f-bf10-267945199555",
            "phone_region": "US",
            "zip_code": "10001",
            "sms_and_call": true,
            "forwarding_to_phone_number": "+13231112233",
            "rcs": true
        }
    ]
}

Order an email sender

Name	Type	Description
name*	String	Name part
domain*	String	Sender domain
plan_id*	String	Payment plan ID

Response example

{
    "count": 1,
    "items": [
        {
            "id": "f41c27d2-1251-488f-bf10-267945199555",
            "name": "[email protected]"
        }
    ]
}

Test purchase

To test this request, you need to include the "test": true parameter in the JSON payload. Once the request is accepted, you will receive a webhook within a few minutes confirming the activation of the sender name.

{
  "test": true,
  "senders" [{
    ...
  }]
}

Once the request is accepted, you should receive a webhook within a few minutes that simulates the sender’s activation. In the production environment, you should receive this webhook within a few hours.

For this test flow, you need to have at least one active paid service. These API’s does not work with the sandbox environment.

Webhooks

You can also receive webhooks when the status of your sender name changes. For this webhooks will be used the same rules like with events related to messaging.

JSON example:

{
  "event": "sender_name_updated",
  "organization_id": "string",
  "phone_number": "+13231112233",
  "sender": "ID string",
  "status": "active",
  "webhook_id": "string"
}

Field	Type	Description
webhook_id	String	Unique identifier of the event.
organization_id	String	ID of the organization to which the sender is assigned.
event	String	Check the Event Types section for possible values.
status	String	New sender name status. Possible values: active, pending, canceled, canceled, suspended .
phone_number	String	Optional Field. Assigned phone number
sender	String	Dedicated sender name ID.

Event Types

All values will be in lowercase and in snake_case format

Event type	Description
sender_name_updated	Your sender has a status update

Headers

These headers will be included in any webhook POST request.

Key	Value
Content-Type	application/json
User-Agent	LoopMessage
Connection	close