Destinations API
This API allows you to configure destinations for your submission data.
You can configure destinations for each of your forms, and when users submit those forms, the data is delivered through all the destinations you’ve set up.
Authentication
To use the API, you’ll need to obtain an access token and pass this along in each call – please see our authentication topic for more information. Your API token can be obtained from your “Edit Organization” screen.
Components
Destinations are made up of a Format, a Transport and optionally a Binary Transport. These are used when creating and updating destinations.
To view a full list of available formats, transports, binary transports and the available parameters for each please use the link below:
Base URL
Because destinations are associated with forms, all your API requests that work with destinations need to identify the form that you’re referring to. So requests will be based on the following URL (note the HTTPS):
https://api.devicemagic.com/api/forms/[form_id]/destinations
where
The form_id is the id of the form you’d like to work with
Viewing Destinations on a Form
To get an overview of all the destinations forms belonging to a form, simply issue an HTTP GET request to the Base URL.
https://api.devicemagic.com/api/forms/[form_id]/destinations.json
This will return a list of all the destinations. e.g.
Request
https://api.devicemagic.com/api/forms/1/destinations.json
Response
{
"destinations": [
{
"id": 1,
"description": null,
"active": true,
"format_type": "text_format",
"format_id": 1,
"transport_type": "email_transport",
"transport_id": 1,
"binary_transport_type": null,
"binary_transport_id": null,
"created_at": "2015-07-23T12:21:19.000Z",
"updated_at": "2015-07-23T12:21:19.000Z"
},
{
"id": 2,
"description": null,
"active": true,
"format_type": "text_format",
"format_id": 2,
"transport_type": "email_transport",
"transport_id": 2,
"binary_transport_type": null,
"binary_transport_id": null,
"created_at": "2015-07-23T12:21:19.000Z",
"updated_at": "2015-07-23T12:21:19.000Z"
}
]
}Viewing Destination Details
To view the details of a single destination, issue an HTTP GET request to the Base URL with the destination_id.
https://api.devicemagic.com/api/forms/[form_id]/destinations/[destination_id].json
e.g.
Request
https://api.devicemagic.com/api/forms/1/destinations/1.json
Response
{
"destination": {
"id": 1,
"description": null,
"active": true,
"format_type": "text_format",
"format_id": 1,
"transport_type": "email_transport",
"transport_id": 1,
"binary_transport_type": null,
"binary_transport_id": null,
"created_at": "2015-07-23T12:22:31.000Z",
"updated_at": "2015-07-23T12:22:31.000Z",
"text_format": {
"id": 1,
"include_images": null,
"created_at": "2015-07-23T12:22:31.000Z",
"updated_at": "2015-07-23T12:22:31.000Z",
"template": null,
"text_intro": null,
"custom_text_content": null,
"render_template_as_html": null,
"location_in_coordinate_format": null,
"include_answer_attributes": null
},
"email_transport": {
"id": 1,
"smtp_address": null,
"smtp_port": null,
"from_domain": null,
"username": null,
"password": null,
"auth_scheme": null,
"from_address": null,
"from_name": null,
"to_addresses": "bob@lol.com",
"to_address_form_field": null,
"subject_template": null,
"body_template": null,
"created_at": "2015-07-23T12:22:31.000Z",
"updated_at": "2015-07-23T12:22:31.000Z",
"use_tls": null,
"via_custom_smtp": null,
"custom_email_content": null,
"to_address_device_attribute": null,
"encryption": 0,
"skip_bounce_list_check": null,
"allow_no_email": null
}
}
} Creating a Destination via JSON
To create a new destination, you need to send an HTTP POST with the destination settings to:
HTTP POST https://api.devicemagic.com/api/forms/[form_id]/destinations.json
In the POST you need to specify a few things for the destination:
description
format_selection
transport_selection
binary_transport_selection (optional)
Then you need to provide the parameters for the format / transports you selected.
An example post:
{
"destination": {
"description": "Some description",
"format_selection": "text_format",
"transport_selection": "email_transport"
},
"email_transport": {
"to_addresses": "test@test.com;test2@test.com"
}
} In the above example I don't need to specify any settings for the "text_format" so I don't send any parameters through for it.
An example post with a binary_transport:
{
"destination": {
"description": "Some description",
"format_selection": "word_format",
"transport_selection": "http_transport",
"binary_transport_selection": "binary_google_drive_transport"
},
"word_format": {
"file_name_template": "My_Doc"
},
"http_transport": {
"uri": "test.com"
},
"binary_google_drive_transport": {
"google_account_email": "myemail@gmail.com"
}
}To view a full list of available formats, transports, binary transports and the available parameters for each please use the link below.
If the creation is successful you will get the destination details returned in the same format as "View destination details" above.
Updating a Destination via JSON
To update a destination, you need to send an HTTP PUT with the destination settings to:
HTTP PUT https://api.devicemagic.com/api/forms/[form_id]/destinations/[destination_id].json
where
[form_id] is the id of the form the destination belongs to
[destination_id] is the id of the destination
For the update, send through all required parameters. Note, you cannot change the components of the destination. For example, a destination in text_format can't be changed to pdf_format. Instead, create a new destination.
An example:
{
"destination": {
"description": "Brand new description",
},
"email_transport": {
"to_addresses": "some_other_address@test.com"
},
"text_format": {
"location_in_coordinate_format": true
}
} You do not need to specify the format_selection, transport_selection or binary_transport_selection as we know what to look for from the destination.
Destroying a Destination
To remove a destination, you need to send an HTTP DELETE to:
HTTP DELETE https://api.devicemagic.com/api/forms/[form_id]/destinations/[destination_id]
You’ll receive a 200 OK if the delete succeeded, and an HTTP error response otherwise.