How to import your integrations into Unified.to

October 25, 2024

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.

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.

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.
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:

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.

Import an API token integration

For single-token integrations, construct your connection object:

{
  "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:

{
  "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

Construct your connection object with the OAuth credentials:

{
  "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"
  }
}

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:

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

Test the imported connection

After creating the connection:

Note the connection ID from the response.
Make a test API call using the new connection ID to verify it works.
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.