How to use the POPVOX API to deliver messages to lawmakers
The POPVOX API uses a token to authenticate users. This token is passed in your request headers. The following two value pairs are required:
Accept:application/json Authorization:Bearer {your token}
In order to send a message to our API - a POST request with the proper headers and the following json payload is required:
{ "data": { "name_prefix": "Ms.", "first_name": "Liz", "last_name": "Russell", "suffix": "", "address1": "11501 Domain Dr.", "address2": null, "city": "Austin", "state": "TX", "zip_code": "78758", "phone_number": "5045551212", "email": "test@testing.com", "custom_subject": "This is the SUBJECT", "message": "This is the MESSAGE", "destination_id": 15313, "main_issue": 13304 } }
Codes to Congress Members are available both in CSV format and through our API. Click here to view those options. Codes to issue areas are available here.
If you already have district information you can pass that through directly into the destination_id
parameter. The format should start with "H" followed by a 2 letter state abbreviation and 2 digit district number. Ex: HTX12
, HTN08
.
Keep in mind that anything less or more than a 5 character string will be rejected. Districts with a single digit should include a leading zero.
curl -X POST \ https://messages.popvox.com/api/send-message \ -H 'accept: application/json' \ -H 'authorization: Bearer {your token here}' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "data": { "name_prefix": "Ms.", "first_name": "Liz", "last_name": "Russell", "suffix": "", "address1": "11501 Domain Dr.", "address2": null, "city": "Austin", "state": "TX", "zip_code": "78758", "phone_number": "5045551212", "email": "test@testing.com", "custom_subject": "This is the SUBJECT", "message": "This is the MESSAGE", "destination_id": 15313, "main_issue": 13304 } }'
In order to send a message to regulations.gov - a POST request with the proper headers and the following json payload is required:
{ "data": { "name_prefix": "Ms.", "first_name": "Liz", "last_name": "Russell", "suffix": "", "address1": "11501 Domain Dr.", "address2": null, "city": "Austin", "state": "TX", "zip_code": "78758", "phone_number": "5045551212", "email": "test@testing.com", "message": "This is the MESSAGE", "destination_id": "WHD-2017-0003-0001", "sponsoring_org": "My Organization", "category": "Association" } }
The destination_id is the docket number of the regulation you are submitting to. You can find this number in the right hand column of the regulation detail page - or in the query string of the url.
Example
The docket number would be "WHD-2017-0003-0001"
curl -X POST \ https://messages.popvox.com/api/send-message \ -H 'accept: application/json' \ -H 'authorization: Bearer {your token here}' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "data": { "name_prefix": "Ms.", "first_name": "Liz", "last_name": "Russell", "suffix": "", "address1": "11501 Domain Dr.", "address2": null, "city": "Austin", "state": "TX", "zip_code": "78758", "phone_number": "5045551212", "email": "test@testing.com", "message": "This is the MESSAGE", "destination_id": "WHD-2017-0003-0001", "sponsoring_org": "My Organization", "category": "Association" } }'
Each request to the API will send a json encoded response back. A successful submission will respond with a response type of success.
{ "response": "success" }
If an error is encountered - a response type of error will be returned with a reason property that will detail what needs attention.
{ "response": "error", "reason": "The phone number field is required." }