Destinations API - Overview

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 button below:

Destination Components Documentation

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://www.devicemagic.com/api/forms/[form_id]/destinations

where

  1. 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://www.devicemagic.com/api/forms/[form_id]/destinations.json

This will return a list of all the destinations. e.g.

Request

https://www.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://www.devicemagic.com/api/forms/[form_id]/destinations/[destination_id].json

e.g.

Request

https://www.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://www.devicemagic.com/api/forms/[form_id]/desinations.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.

Destination Components Documentation

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://www.devicemagic.com/api/forms/[form_id]/desinations/[destination_id].json

where

  1. [form_id] is the id of the form the destination belongs to
  2. [destination_id] is the id of the destination

For the update you just need to send through parameters you would like to change, you cannot change the components of the destination, just the values inside.

So you can't change from a text_format to a pdf_format, you will need to 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://www.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.

Have more questions? Submit a request

Comments

Powered by Zendesk