---
title: "How to migrate or import your integrations into Unified.to"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_migrate_or_import_your_integrations_into_unified-icon.webp
date: 2024-10-25T00:00:00.000Z
tag: Guides
description: "This guide explains how to import your existing integrations into Unified.to, effectively creating new connections using your existing customer credentials. A..."
url: "https://docs.unified.to/guides/how_to_migrate_or_import_your_integrations_into_unified"
---

# How to migrate or import your integrations into Unified.to
------
_October 25, 2024_

![app.unified.to_connections_import_typedropbox.png](https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_migrate_or_import_your_integrations_into_unified-0.png)


This guide explains how to import your existing integrations into Unified.to, effectively creating new connections using your existing customer credentials. A connection is a secure link between your application and your customer's third-party account. 


While connections are typically created through an auth flow where users grant access through the provider's authorization page, you can also create connections by importing existing credentials that your customers have already provided to you.


## Before you begin


This guide assumes you have:

- A Unified.to account.
- Existing customer credentials for the integrations you want to import.
- Basic understanding of REST APIs, authentication flows, and [connections](https://docs.unified.to/guides/end_users_integrations_and_connections#end-users-integrations-and-connections).

## Understand the authentication types


Before importing your integrations, you need to determine which authentication type each integration uses. Unified.to supports two main authentication flows:


### API token authentication

- Simple token: Requires a single token or key.
- Multi-field token: Requires multiple credentials (e.g. API key + domain).

### OAuth 2 authentication

- Requires client credentials (client ID and secret).
- Requires access tokens and optional refresh tokens.
- May include additional user information e.g. emails, names.

## Check instructions for the integration you want to import


The Unified.to Core API contains information that will help you determine what you need to successfully import your integrations.

1. Make a GET request to the `/unified/integration` endpoint to get information about the integration you want to import, passing in the categories and/or names of the integrations you are interested in.
2. Check the following fields in the response:
    - `token_names`: Lists required credential fields for API token authentication.
    - `token_instructions`: Provides guidance on where to find these credentials.

For example:


```javascript
const baseUrl = 'https://api.unified.to/unified/integration';
const params = new URLSearchParams({
  categories: ['ats', 'crm'].join(',')
});
const url = `${baseUrl}?${params}`;

// Make the request
fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Accept': 'application/json'
  }
})
.then(response => {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json();
})
.then(integrations => {
  // Loop through each integration and log its auth details
  integrations.forEach(integration => {
    console.log(`\n=== ${integration.name} ===`);
    
    // Log token information if it exists
    if (integration.token_names && integration.token_names.length > 0) {
      console.log('Required credentials:', integration.token_names);
      console.log('How to find credentials:');
      integration.token_instructions?.forEach((instruction, index) => {
        console.log(`${index + 1}. ${instruction}`);
      });
    } else {
      console.log('No token credentials required (likely uses OAuth)');
    }
  });
})
.catch(error => {
  console.error('Error fetching integrations:', error);
});

/* Example output:

=== ActiveCampaign ===
Required credentials: ["API Key", "Domain"]
How to find credentials:
1. Your API key can be found in your account on the Settings page under the "Developer" tab...
2. Your API URL can be found in your account on the My Settings page under the "Developer" tab...

=== HubSpot ===
No token credentials required (likely uses OAuth)

*/
```


 **API reference:** [Get all integrations](https://docs.unified.to/unified/integration/Returns_all_integrations).


## Import an API token integration


For single-token integrations, construct your connection object:


```json
{
  "integration_type": NAME_OF_INTEGRATION,
  "permissions": [PERMISSIONS],
  "categories": [CATEGORIES],
  "environment": "Production", // or any other non-sandbox environment
  "auth": {
    "token": "your_customer_token"
  }
}
```


For multi-field token integrations, use the `other_auth_info` array:


```json
{
  "integration_type": NAME_OF_INTEGRATION,
  "permissions": [PERMISSIONS],
  "categories": [CATEGORIES],
  "environment": "Production", //  or any other non-sandbox environment
  "auth": {
    "token": "your_customer_token"
    "other_auth_info": [
      "first_credential",
      "second_credential"
    ]
  }
}
```


**Important**: The order of credentials in `other_auth_info` must match the order of the `token_names` from the integration instructions (see above).


## Import an OAuth 2.0 integration

1. Construct your connection object with the OAuth credentials:

```json
{
  "integration_type": NAME_OF_INTEGRATION,
  "permissions": [PERMISSIONS],
  "categories": [CATEGORIES],
  "environment": "Production", //  or any other non-sandbox environment
  "auth": {
    "access_token": "customer_access_token",
    "refresh_token": "customer_refresh_token",
    "expiry_date": "2024-12-31T23:59:59Z",
    "emails": ["user@example.com"],
    "name": "User Name"
  }
}
```

1. Log into the developer account for the provider whose integrations you are importing. Update your redirect URIs to point to Unified.to: `https://api.unified.to/oauth/code`

**Notes**:

- Set `expiry_date` to the token's expiration date (if known) or today's date.
- Include the authenticating user's email and name if available.

## Create the connection


Make a POST request to create the connection. Example using `curl`:


```shell
curl -X POST "<https://api.unified.to/unified/connection>" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "integration_type": "your_integration_type",
    "permissions": ["required_permissions"],
    "categories": ["integration_category"],
    "auth": {
      // Your auth object here
    }
  }'
```


**API reference**: [Create a connection](https://docs.unified.to/unified/connection/Create_connection)


## Test the imported connection


After creating the connection:

1. Note the connection ID from the response.
2. Make a test API call using the new connection ID to verify it works.
3. If the call fails, check the error message and verify your auth credentials.

## Best practices when importing a connection

- Always include relevant `permissions` for the minimum set of data access you require.
- Use a non-sandbox `environment`.
- Store the connection ID securely for future API calls.
- Consider adding `external_xref` to link the connection to your customer's ID.

## See also

- [How to associate a connection ID with your end-user](https://docs.unified.to/guides/how_to_associate_a_connection_id_with_your_end_user#how-to-associate-a-connection-id-with-your-end-user)
- [How to troubleshoot unhealthy connections](https://docs.unified.to/guides/how_to_troubleshoot_unhealthy_connections#how-to-troubleshoot-unhealthy-connections)
- [How to create and configure webhooks](https://docs.unified.to/guides/how_to_create_and_configure_webhooks)