API Reference - POST /textmessaging/sendmessage

Page content

See More

The send message endpoint is designed to allow agencies to send text messages to users of USAJOBS. The intended use of this API is to give important updates regarding applications or similar events to a user's registered mobile phone.

Resource

POST /api/textmessaging/sendmessage

Authorization

In order to call this api method, you must be an approved Talent Acquision System with a sponsoring agency. The Send Message endpoint requires that the calling application's IP address is registered with USAJOBS. An API key is also required to be passed in through a X-Api-Key header. For registering your application's IP address with us and/or getting an API key, please contact the help desk.

JSON Body Properties

Parameter Name Description

AlternateDocumentID

Unique application identifier passed between USAJOBS and the Talent Acquisition System.

Message

The contents of the text message.

Request

JSON: 
{
    "alternateDocumentID": "xxxxxxxxxxxxx",
    "message": "Sample text message"
}

Response

JSON: 
{  
    "responseId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}
Name Description Type
responseId The text message identifier that can be used by the status endpoint to see the send status for a text message. guid

Error Codes

If any of the below error codes are provided, the HTTP status code will be 400.

Code Description
AlternateDocumentIDEmpty An alternate document ID was not passed in the request.
MessageEmpty A message was not passed in the request.
MessageTooLong The message exceeded the max character length (UTF8).
ApplicationNotFound An application could not be found for the provided alternate document ID.
NotOptedIn The user has not opted into text messaging.
OptInNotConfirmed The user has not confirmed their opt-in via text message response.
InvalidPhoneNumber The phone number is invalid for receiving text messages. 
JSON: 
{
    "error": {
        "code": "BadRequest",
        "message": "The length of 'Message' must be 620 characters or fewer. You entered 1122 characters.",
        "target": "Message",
        "details": [
            {
                "code": "MaximumLength",
                "message": "The length of 'Message' must be 620 characters or fewer. You entered 1122 characters.",
                "target": "message",
                "maxLength": 620
            }
        ]
    }
}