Order new sender names

Use this method for bulk ordering new sender names.

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

Request body

Each sender is a separate item in the array. If you pass 2 items, it means ordering two separate sender names.

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

Order sender with a phone number

Possible values for each array element:

Name	Type	Description
plan_id*	String	Payment plan ID
phone_region*	String	Default value US. Possible values: US, GB, or AU*
available_number_id	String	Optional. ID of an available phone number returned by the Available phone numbers section.
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.

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]"
        }
    ]
}

Available phone numbers

If registered phone numbers are currently available, you can purchase them through the API. These numbers are activated immediately after a successful purchase, without waiting for the usual sender activation process.

Get available phone numbers

GET https://a.loopmessage.com/api/v1/sender/available-numbers/

Use this method to retrieve the phone numbers that are currently available for purchase. You can optionally filter the results by region using the region query parameter.

Response example:

{
  "items": [
    {
      "id": "f41c27d2-1251-488f-bf10-267945199555",
      "phone": "+13231111111",
      "region": "US"
    }
  ]
}

Reserve an available phone number

PUT https://a.loopmessage.com/api/v1/sender/available-numbers/{available_number_id}/

Use this method to temporarily reserve a phone number while the user is considering the purchase. The reservation lasts for 3 minutes. During this time, no one else can purchase the number.

The available_number_id is the id returned by the GET request above. The request does not require a body. If you received status code 200, the number has been successfully reserved.

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

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