Skip to main content

Endpoints

This section covers only general endpoint interaction requirements with a couple examples. For detailed endpoint developer reference, please refer to the Developer Documentation.

Authentication​

Endpoint Restrictions​

The SMS and MM4 endpoints are separately controlled by license. If you're having problems accessing one of the scanning endpoints, please reach out to support.

Get Token​

/authorize/v1

PMSS uses Auth0 for authorization. A client_id and client_secret will be supplied that can be used to obtain a token. This token would then be used for all subsequent requests.

Please contact support for issues with your client_id or client_secret.

info

Tokens are valid for 1 week.

curl --request POST \
  --url https://api-us.pmss.proofpoint.com/v1/authorize \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "string",
  "client_secret": "string",
  "grant_type": "client_credentials"
}'
{
  "access_token": "eyJhbGciOiJIUzI1...",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Type Requirements​

The message type is passed in via the route accessed. The 3 primary scanning endpoints are:

  • /scan/v1/sms/{type}
  • /scan/v1/sms/long/{type}
  • /scan/v1/mm4/{type}

Depending on which type of message to be sent, there are certain elements that must be present for the query to be successful. PMSS has various endpoints for SMS and MM4 messages, depending on the message "type".

Message types are:

  • Application Originated
    • Messages sent from an application or service (e.g., a server or software) to a mobile device, such as automated alerts or notifications.
  • Application Terminated
    • Messages received by an application or service from a mobile device, typically as a response or acknowledgment to a prior interaction.
  • Mobile Originated
    • Messages initiated from a mobile device and sent to a network, application, or another device, like a text message sent by a user.
  • Mobile Terminated
    • Messages directed to and received by a mobile device from a network, application, or another device, such as an incoming text or call.

Application Originated​

Whether SMS or MM4, Application Originated messages are scanned using ao type in the query path.

warning

Application Originated messages will fail without the following elements:

  • Account ID that identifies the sender
  • Account age epoch
  • From MDN age epoch

The following elements must be present for an Application Originated message:

  • account_id
  • account_age
  • from_age
  • to
  • from
  • body
tip

Sub-Account ID and Sub-Account Age can optionally be included for resellers.

Brand/Campaign Registry Details​

Messages with Brand details must have all of the necessary information:

  • brand_id
  • brand_name
  • campaign_id
  • campaign_name
warning

If any of the above are supplied, then all are required.

Account / Sub-Accounts​

The account identifier and account age are required for AO messages and optional for all other message types.

If a sub-account id is provided, then the main account id and age must be supplied as well.

SMS​

Encoding Enforcement​

By default, PMSS runs in "relaxed" mode, meaning messages can exceed their length/size restrictions. Strict mode enforces classic limits for traditional setups while relaxed mode accommodates oversized messages if your upstream permits, ideal for advanced networks.

A third option, "info" will run the same checks as strict mode. However, instead of returning an error, additional information about the message encoding is included in the query response.

To override the "relaxed" mode with either "strict" or "info", you can include the "encoding" parameter with one of the two values in the request body.

{
  "encoding": "strict"
}

/scan/v1/sms/{type}

SMS Examples​

Application Originated / DCS 0​

  • Application Originated (AO)
  • DCS 0 (Latin-1)

Required Parameters

{
  "dcs": 0,
  "account_id": str,
  "account_age": epoch int,
  "from_age": epoch int,
  "to": str,
  "from": str,
  "body": str [base64 encoded body, after Latin-1 encoding]
}

Optional Parameters

{
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1"
}

Sample curl (see "API Documentation for more examples"):

curl --request POST \
  --url https://api-us.pmss.proofpoint.com/scan/v1/sms/ao \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <bearer token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "dcs": 0,
  "account_id": "cpaas-customer-parent-1234",
  "account_age": 1738257512,
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1",
  "from": "+15551234567",
  "from_age": 17384757548,
  "to": "+15559876543",
  "body":  str [base64 encoded body, after Latin-1 encoding]
}'

1 - MO / DCS 8​

  • Mobile Originated (MO)
  • DCS 8 (UTF-16 (UCS2))

Required Parameters

{
  "dcs": 0,
  "to": str,
  "from": str,
  "body": str [base64 encoded body, after UTF-16 encoding]
}

Optional Parameters

{
  "account_id": "cpaas-customer-parent-1234",
  "account_age": 1738257512,
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1"
}
curl --request POST \
  --url https://api-us.pmss.proofpoint.com/scan/v1/sms/mo \
  --header 'Accept: application/json' \
  --header 'Authorization: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "dcs": 0,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "src_ip": "192.168.1.1",
  "from": "+15551234567",
  "to": "+15559876543",
  "body": "SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZS4="
}'

Long SMS​

/scan/v1/sms/long/{type}

Long (multi-part) SMS require Segmentation and Reassembly (SAR) parameters to be passed in with the request body. These values indicate a message identifier, a count of total message parts and an indication as the index of the current message part.

Example 1​

  • Application Originated (AO)
  • DCS 8 (UTF-16)

Required Parameters

{
  "dcs": 8,
  "account_id": str,
  "account_age": epoch int,
  "from_age": epoch int,
  "to": str,
  "from": str,
  "body": str [base64 encoded body, after UTF-16],
  "sar_msg_ref_num": 12345,
  "sar_total_segments": 3,
  "sar_segment_seqnum": 2
}

Optional Parameters

{
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1"
}

Sample curl (see "Developer Documentation for specific API requirements and examples"):

curl --request POST \
  --url https://api-us.pmss.proofpoint.com/scan/v1/sms/long/ao \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <bearer token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "dcs": 0,
  "account_id": "cpaas-customer-parent-1234",
  "account_age": 1738257512,
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1",
  "from": "+15551234567",
  "from_age": 17384757548,
  "to": "+15559876543",
  "body":  str [base64 encoded body, after UTF-16 encoding],
  "sar_msg_ref_num": 12345,
  "sar_total_segments": 3,
  "sar_segment_seqnum": 2
}'

MM4​

/scan/v1/mm4/{type}

For MM4 messages, the sender and recipient MDN(s) are pulled from the message body, so there is no need to include them in the request JSON body.

note

The max size for MM4 messages is 13.9MB (13981016 bytes; ~10MB before base64 encoding).

Example 1​

  • Application Originated (AO)

Required Parameters

{
  "account_id": str,
  "account_age": epoch int,
  "from_age": epoch int,
  "body": str [base64 full-headers body]
}

Optional Parameters

{
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1"
}

Sample curl (see "Developer Documentation for specific API requirements and examples"):

curl --request POST \
  --url https://api-us.pmss.proofpoint.com/scan/v1/mm4/ao \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <bearer token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "cpaas-customer-parent-1234",
  "account_age": 1738257512,
  "sub_account_id": "cpaas-customer-child-1234",
  "sub_account_age": 2348762234,
  "sender_class": "promotional",
  "message_id": "msg-abc123",
  "message_sent": 1738257512,
  "brand_id": "Brand123",
  "brand_name": "Acme",
  "campaign_id": "ac3723",
  "campaign_name": "AcmePromo",
  "src_ip": "192.168.1.1",
  "from_age": 17384757548,
  "body":  str [base64 full-headers body]
}'

SMS Key Points​

Data Encoding​

SMS messages can be scanned using the /scan/v1/sms/{type} endpoint where type is one of:

  • Application Originated - ao
  • Application Terminated - at
  • Mobile Originated - mo
  • Mobile Terminated - mt

Process messages in any SMS encoding format, including:

  • GSM-7 (e.g., standard text like "Hello")
  • Latin-1 (e.g., text with ñ or á)
  • 8-bit binary (e.g., binary data like 0xFF)
  • UTF-16/UCS2 (e.g., emoji like 😊)

The Data Coding Scheme (DCS) defines the encoding format for each message type, and selecting the correct DCS is crucial to avoid errors. If the DCS does not match the message’s encoding, an API error will result. For example, using DCS 0 (GSM 7-bit) for a UTF-16 message with emojis will cause an error. Specify the DCS in API requests to control encoding, as shown in the table and example below:

TypeDCSDescriptionMax Length
ao0, 3Latin-1140 bytes
ao48-bit binary140 bytes
ao8UTF-16 (UCS2)70 characters
at0, 3Latin-1140 bytes
at48-bit binary140 bytes
at8UTF-16 (UCS2)70 characters
mo0GSM 7-bit160 characters
mo48-bit binary140 bytes
mo8UTF-16 (UCS2)70 characters
mt0GSM 7-bit160 characters
mt48-bit binary140 bytes
mt8UTF-16 (UCS2)70 characters

All SMS bodies must be base64 encoded

Multi-Part SMS​

Long SMS messages that would normally exceed the max message length can be broken up into multiple parts and sent one at a time. The handset receives each message and then presents them all as a single, reassembled message once all parts have arrived. If any of the parts are blocked, then none of the message will appear on the handset.

All parts of a multi-part SMS must have 3 Segmentation and Reassembly (SAR) components include in the request body:

{
  "sar_msg_ref_num": 0-65535 int,
  "sar_total_segments": 1-65535 int,
  "sar_segment_seqnum": 1-65535 int
}
sar_msg_ref_num - int [0-65535] - An identifier that is common across all message parts.
sar_msg_total_segments - int [1-65535] - Indicator showing total number of messags parts.
sar_segment_seqnum - int [1-65535] - Indicator showing which nmber the current message is.