API Reference

This is API version 2.1. Make sure you are using https://www.import2.com/api/v2.1 as base URL for all your 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/v2.1/imports/3514012b6860e8

Heads up! If you don't have an API token yet, please contact us at partners@import2.com.

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 2, but there is a version 3 already available, then Sandbox API will be behaving like API v3.

Response Codes and Errors

All requests and responses are encoded as JSON.

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.
404
Not Found. The requested resource or migration does not exist, has been archived, or cancelled.
422
The request was well-formed but was unable to be followed due to validation rules. Parse response body.

GET /tools

Returns list of tools that are supported as data source for your app. 

1
2

curl -i -X GET -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
	https://www.import2.com/api/v2.1/tools

Response will have HTTP status 200 and body containing array of source tools including their names and slugs: 

1
2
3
4
5
6
7
8

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

[
  {"name":"wordpress", "label":"Wordpress"},
  {"name":"posterous", "label":"Posterous"},
  {"name":"tumblr", "label":"Tumblr"}
]

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_instance_url":"http://myblog.tumblr.com/", "destination_username":"username", "destination_token":"token"}' \
https://www.import2.com/api/v2.1/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_token":["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
8

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

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

Properties

Name Required? Description Example values
source_tool required Name of the source tool. Items will be exported from this tool to destination tool. “posterous”
“highrise”
destination_instance_url optional Url of the destination tool instance. “http://myblog.tumblr.com/”
“https://mycorp.salesforce.com/”
destination_username optional Username used to sign in into the destination tool (or email address if it is used in destination tool). “janeimport”
“jane.import@mycorporation.com”
destination_token optional API token used to access destination tool. “apitoken”
start_full optional A boolean flag to initiate immediate full migration, bypassing the sample migration step. It automatically designates the migration as sponsored by you. Default value is false. true
false

GET /imports

Returns list of all imports for the given username in the destination tool. 

1
2

curl -i -X GET -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
https://www.import2.com/api/v2.1/imports?destination_username=username

If no imports found, then you will receive response with HTTP status 200 and response body will contain empty array 

1
2
3
4

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

[]

If imports for such username exist, then response will contain list of such imports including their identifications and status: 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

[
  {
    "id":"my-import-id-1",
    "token":"my-import-unique-token-1",
    "status":"Import Completed",
    "items":{"accounts":123, "contacts":234},
    "users":{"source_tool":5, "destination_tool":4, "matched":3}
  },
  {
    "id":"my-import-id-2",
    "token":"my-import-unique-token-2",
    "status":"Sample Import in Progress",
    "items":{"accounts":123, "contacts":234},
    "users":{"source_tool":5, "destination_tool":4, "matched":3}
  },
]

Parameters

Name Required? Description Example values
destination_username required Username used to sign in into the destination tool (or email address if it is used in destination tool). “janeimport”
“jane.import@mycorporation.com”

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/v2.1/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
9
10

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

{
  "id":"my-import-id",
  "token":"my-import-unique-token",
  "status":"Import Completed",
  "items":{"accounts":123, "contacts":234},
  "users":{"source_tool":5, "destination_tool":4, "matched":3}
}

Import Statuses

Status Description
Collecting credentials Customer is authorizing access to their source and destination applications.
Waiting to start sample migration Customer has provided credentials, but hasn’t started the sample migration yet.
Sample migration in progress Sample migration is currently in progress.
Sample migration completed Sample migration has been finished. Customer can review imported data in your application.
Migration in progress Full migration is currently in progress.
Migration completed Full migration has been finished. Customer can start using their instance of your application.
Undo in progress The migration is being undone.
Migration cleaned The migration was undone.
In preparation Migration is paid and ready to be started.

POST /imports/:id/payment/accept

Accept sponsorship (i.e. obligation to pay) for the import identified by the given id. After this the customer will be able to start full migration from the Import2 UI. 

1
2

curl -i -X POST -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
https://www.import2.com/api/v2.1/imports/my-import-id/payment/accept

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 empty body 

1

HTTP/1.1 200

POST /imports/:id/payment/reject

Reject sponsorship for the import identified by the given id. After this the customer will be able to purchase full migration from Import2 by themselves. 

1
2

curl -i -X POST -u aafbdfde226327dafc73:X -H "Content-Type: application/json" \
https://www.import2.com/api/v2.1/imports/my-import-id/payment/reject

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 empty body 

1

HTTP/1.1 200