Using the API

Using Import2 API, you can provide customers of your application with a dead-simple migration process from the app they are substituting with yours. With this guide we will explain and provide code snippets for all common integration scenarios.

All requests and responses are encoded as JSON.

This is API version 1. Make sure you are using https://www.import2.com/api/v1 as base URL for all your API requests.

Registering Your Application

Currently to register your app you have to contact us at hassle.free.migration@import2.com. We will send you secret API token, which is required to perform API requests.

Authentication

Import2 API uses HTTP Basic Authentication. We expect to receive your API token as value of username parameter. Here is an example of using API token through curl:

1

curl -i -u aafbdfde226327dafc73:X https://www.import2.com/api/v1/imports/3514012b6860e8

Sandbox

All of the API endpoints (unless stated otherwise) are also available at Sandbox API version: https://www.import2.com/api/sandbox (i.e. just replace api version in the URL with ‘sandbox’). Sandbox API endpoints behave exactly as real API, except:

POST/PUT

will run all the validation rules and send corresponding response, but will not actually create or update any objects

GET

will return pre-defined static responses

DELETE

will return pre-defined static responses, but will not actually delete any objects

You can play with Sandbox API without being worried about hitting any limits or performing actual imports.

Heads up! Sandbox mimics the behavior of the latest available API version! If you’re developing against version 1, but there is a version 2 already available, then Sandbox API will be behaving like API v2.

Response Codes and Errors

API uses HTTP status codes to inform you about request result. Here are the most frequently seen response codes and their interpretation:

200

Request has succeeded. Parse response body.

201

Request has succeeded and object was created. Parse response body.

400

Request cannot be fulfilled due to bad syntax.

401

Unauthorized. Either no API token was included in the request or API token was invalid.

422

The request was well-formed but was unable to be followed due to validation rules. Parse response body.

Workflow of Creating New Import

Step by Step Workflow

Steps that are labelled with Your App take place in your application. Import2 labelled steps take place in Import2.

Your App

1. Customer clicks on ‘Import’ link in your app

Your App

2. Your app sends a POST /imports request to Import2

Import2

3. Import2 creates a partially initialized import and responds with import id and URL where your app should redirect customer: import2_redirect_url

Your App

4. Your app stores import id and redirects customer to the import2-redirect-url

Import2

5. Customer enters credentials to access source data and starts the import

Import2

6. Import2 redirects customer to redirect URL of your app that was specified during your app registration: app_redirect_url along with import id and import status

Your App

7. Your app displays import progress page to the customer

Import2

8. Import2 performs import and notifies your app about import progess via webhook URL that was specified during your app registration: app_webhook_url

Functionality to Implement

This is the list of functionality that needs to be implemented in order to ensure the best experience for your customers.

• Import page where customer is able to click on the tool she wishes to import her data from. Upon clicks your app should send an API request to Import2 and process response by storing import id and redirecting customer to a URL specified in response
• Import status page where customer is redirected after starting her import and where she can follow the progress of the import
• Webhook handler that is used by Import2 to notify your app about import progress

API Reference

POST /imports

Creates a partially initialized new import. Responds with the import id and URL of the page where your customer should be redirected.

1
2
3

curl -i -X POST -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
	-d '{"source_tool":"posterous", "destination_tool":"tumblr", "destination_instance_url":"http://myblog.tumblr.com/", "destination_username":"username", "destination_password":"password"}' \
	https://www.import2.com/api/v1/imports

If validation fails, then you will receive response with HTTP status 422 and body containing validation errors:

1
2
3
4
5
6
7
8

HTTP/1.1 422
Content-Type: application/json

{
	"source_tool":["is not supported"],
	"destination_instance_url":[], "destination_username":[], "destination_password":["can't be blank"],
	"destination":["Couldn't access your Tumblr account due to: 401 Unauthorized"]
}

If validation succeeds and import was created, then response will have HTTP status 201 and body containing import identification and redirect URL:

1
2
3
4
5
6
7

HTTP/1.1 201 Created
Content-Type: application/json

{
	"id":"ae2cfc164cb94f67f735581d7f9a3c09",
	"redirect_url":"https://www.import2.com/imports/7f735581d7f9a3c09/ae2cfc164cb94f67f735581d7f9a3c09"
}

Properties

GET /imports/:id

Returns status of the import identified by the given id.

1
2

curl -i -X GET -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
	https://www.import2.com/api/v1/imports/my-import-id

If import is not found, was cancelled or archived, then you will receive response with HTTP status 404 .

1

HTTP/1.1 404

If import exists — response will have HTTP status 200 and body containing import identification, status and warnings (if there are any):

1
2
3
4
5
6
7
8

HTTP/1.1 200 Ok
Content-Type: application/json

{
	"id":"my-import-id",
	"status":"finished",
	"warnings":{"attachments":{"attachment-id":{"name":"sales offer.doc", "parent_id":"email-id", "parent_item":"emails", "warning":"exceeds maximum size"}}}
}

Webhook Reference

POST webhook

Sends import status updates to the webhook URL specified while registering your application via HTTP Post request. Currently, webhook functionality doesn’t re-send import status if your app was unreachable or has responded with an HTTP error. Payload example:

1
2
3
4
5
6
7

Content-Type: application/json

{
	"id":"my-import-id",
	"status":"in_progress",
	"warnings":{"attachments":{"attachment-id":{"name":"sales offer.doc", "parent_id":"email-id", "parent_item":"emails", "warning":"exceeds maximum size"}}}
}