Delivery API usage instructions

How to use the POPVOX API to deliver messages to lawmakers

How to form requests:


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}

Sending a message via the API (congressional offices):


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

Looking for destination_id or main_issue codes?

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.

Already have the proper district for House delivery?

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.

The following would constitue a valid form submission via cURL:

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
	}
}'

Sending a message via the API (regulations):


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

Where do I find the destination_id for a regulation?

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


https://www.regulations.gov/document?D=WHD-2017-0003-0001

The docket number would be "WHD-2017-0003-0001"

The following would constitue a valid form submission via cURL:

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

Responses:


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