Get Integration Details

curl -X GET "https://api.hooked.so/v1/integration/int_yt_abc123" \
  -H "x-api-key: your_api_key_here"

const integrationId = 'int_yt_abc123';

const response = await fetch(`https://api.hooked.so/v1/integration/${integrationId}`, {
  method: 'GET',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY
  }
});

const data = await response.json();

if (data.data.health.status !== 'healthy') {
  console.log('Integration needs reconnection!');
} else {
  console.log('Integration is healthy');
}

import requests

integration_id = 'int_yt_abc123'

response = requests.get(
    f'https://api.hooked.so/v1/integration/{integration_id}',
    headers={'x-api-key': 'your_api_key_here'}
)

data = response.json()
health = data['data']['health']

if health['status'] != 'healthy':
    print(f"Integration needs reconnection: {health['status']}")
else:
    print("Integration is healthy")

{
  "success": true,
  "data": {
    "id": "int_yt_abc123",
    "type": "youtube",
    "identifier": "UC1234567890",
    "account": {
      "id": "UC1234567890",
      "name": "My YouTube Channel",
      "username": "mychannel",
      "avatarUrl": "https://yt3.ggpht.com/..."
    },
    "health": {
      "status": "healthy",
      "tokenValid": true,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-15T08:30:00.000Z"
  }
}

{
  "success": true,
  "data": {
    "id": "int_tt_xyz789",
    "type": "tiktok",
    "identifier": "@myaccount",
    "account": {
      "id": "6912345678901234567",
      "name": "My TikTok",
      "username": "myaccount",
      "avatarUrl": "https://p16-sign.tiktokcdn.com/..."
    },
    "health": {
      "status": "expired",
      "tokenValid": false,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-10T12:00:00.000Z"
  }
}

{
  "code": "not_found",
  "message": "Integration not found",
  "details": {
    "resource_id": "int_invalid",
    "resource_type": "Integration"
  }
}

GET

integration

{integrationId}

curl -X GET "https://api.hooked.so/v1/integration/int_yt_abc123" \
  -H "x-api-key: your_api_key_here"

const integrationId = 'int_yt_abc123';

const response = await fetch(`https://api.hooked.so/v1/integration/${integrationId}`, {
  method: 'GET',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY
  }
});

const data = await response.json();

if (data.data.health.status !== 'healthy') {
  console.log('Integration needs reconnection!');
} else {
  console.log('Integration is healthy');
}

import requests

integration_id = 'int_yt_abc123'

response = requests.get(
    f'https://api.hooked.so/v1/integration/{integration_id}',
    headers={'x-api-key': 'your_api_key_here'}
)

data = response.json()
health = data['data']['health']

if health['status'] != 'healthy':
    print(f"Integration needs reconnection: {health['status']}")
else:
    print("Integration is healthy")

{
  "success": true,
  "data": {
    "id": "int_yt_abc123",
    "type": "youtube",
    "identifier": "UC1234567890",
    "account": {
      "id": "UC1234567890",
      "name": "My YouTube Channel",
      "username": "mychannel",
      "avatarUrl": "https://yt3.ggpht.com/..."
    },
    "health": {
      "status": "healthy",
      "tokenValid": true,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-15T08:30:00.000Z"
  }
}

{
  "success": true,
  "data": {
    "id": "int_tt_xyz789",
    "type": "tiktok",
    "identifier": "@myaccount",
    "account": {
      "id": "6912345678901234567",
      "name": "My TikTok",
      "username": "myaccount",
      "avatarUrl": "https://p16-sign.tiktokcdn.com/..."
    },
    "health": {
      "status": "expired",
      "tokenValid": false,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-10T12:00:00.000Z"
  }
}

{
  "code": "not_found",
  "message": "Integration not found",
  "details": {
    "resource_id": "int_invalid",
    "resource_type": "Integration"
  }
}

Try it out! Use the API playground on the right to test the Get Integration Details endpoint directly.

Overview

Get detailed information about a specific connected social platform, including account details and connection health status. Use this to:

Verify if a connection is still valid before scheduling
Check if tokens have expired and need re-authentication
Get account details for display purposes

If the health status shows expired or error, the user needs to reconnect the account through the Hooked Dashboard.

Endpoint

GET /v1/integration/{integrationId}

Path Parameters

string

required

The unique ID of the integration to retrieve

Headers

string

required

Your API key from API Settings

Response

boolean

Whether the request was successful

object

Show Integration Object

string

Unique integration ID

string

Platform type: youtube, tiktok, or instagram

string

Platform-specific identifier (channel ID, username, etc.)

object

Connected account information

Show Account Object

string

Platform account ID

string

Display name of the account

string

Username or handle

string

Profile picture URL

object

Connection health status

Show Health Object

string

Health status:

healthy - Connection is working properly
expired - Token has expired, needs reconnection
error - Connection error, needs reconnection

boolean

Whether the access token is still valid

string

ISO 8601 timestamp of when health was checked

string

When the integration was connected

Request Example

curl -X GET "https://api.hooked.so/v1/integration/int_yt_abc123" \
  -H "x-api-key: your_api_key_here"

const integrationId = 'int_yt_abc123';

const response = await fetch(`https://api.hooked.so/v1/integration/${integrationId}`, {
  method: 'GET',
  headers: {
    'x-api-key': process.env.HOOKED_API_KEY
  }
});

const data = await response.json();

if (data.data.health.status !== 'healthy') {
  console.log('Integration needs reconnection!');
} else {
  console.log('Integration is healthy');
}

import requests

integration_id = 'int_yt_abc123'

response = requests.get(
    f'https://api.hooked.so/v1/integration/{integration_id}',
    headers={'x-api-key': 'your_api_key_here'}
)

data = response.json()
health = data['data']['health']

if health['status'] != 'healthy':
    print(f"Integration needs reconnection: {health['status']}")
else:
    print("Integration is healthy")

Response Examples

{
  "success": true,
  "data": {
    "id": "int_yt_abc123",
    "type": "youtube",
    "identifier": "UC1234567890",
    "account": {
      "id": "UC1234567890",
      "name": "My YouTube Channel",
      "username": "mychannel",
      "avatarUrl": "https://yt3.ggpht.com/..."
    },
    "health": {
      "status": "healthy",
      "tokenValid": true,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-15T08:30:00.000Z"
  }
}

{
  "success": true,
  "data": {
    "id": "int_tt_xyz789",
    "type": "tiktok",
    "identifier": "@myaccount",
    "account": {
      "id": "6912345678901234567",
      "name": "My TikTok",
      "username": "myaccount",
      "avatarUrl": "https://p16-sign.tiktokcdn.com/..."
    },
    "health": {
      "status": "expired",
      "tokenValid": false,
      "lastChecked": "2024-03-15T10:00:00.000Z"
    },
    "createdAt": "2024-01-10T12:00:00.000Z"
  }
}

{
  "code": "not_found",
  "message": "Integration not found",
  "details": {
    "resource_id": "int_invalid",
    "resource_type": "Integration"
  }
}

Health Status Values

Status	Description	Action Required
`healthy`	Connection is working, token is valid	None
`expired`	Access token has expired	User must reconnect in dashboard
`error`	Connection error or missing token	User must reconnect in dashboard

Checking Health Before Scheduling

It’s a good practice to check integration health before scheduling a video:

async function scheduleIfHealthy(videoId, integrationId, scheduledDateTime) {
  // Check health first
  const healthResponse = await fetch(
    `https://api.hooked.so/v1/integration/${integrationId}`,
    { headers: { 'x-api-key': process.env.HOOKED_API_KEY } }
  );

  const { data: integration } = await healthResponse.json();

  if (integration.health.status !== 'healthy') {
    throw new Error(`Integration ${integration.type} needs reconnection`);
  }

  // Proceed with scheduling
  const scheduleResponse = await fetch(
    'https://api.hooked.so/v1/schedule/create',
    {
      method: 'POST',
      headers: {
        'x-api-key': process.env.HOOKED_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ videoId, integrationId, scheduledDateTime })
    }
  );

  return await scheduleResponse.json();
}

Next Steps

List Integrations

View all connected platforms

Disconnect

Remove a connected account

Schedule Video

Schedule a video for publishing

Dashboard

Reconnect accounts in dashboard

Authorizations

x-api-key

string

header

required

Path Parameters

integrationId

string

required

Integration ID

Response

200 - application/json

Success

success

boolean

data

object

Show child attributes

Getting Started

Resources

Videos

Templates

Trends

Niches

Social Accounts

Social Search

Scheduling

Overview

Endpoint

Path Parameters

Headers

Response

Request Example

Response Examples

Health Status Values

Checking Health Before Scheduling

Next Steps

List Integrations

Disconnect

Schedule Video

Dashboard

Authorizations

Path Parameters

Response

​Overview

​Endpoint

​Path Parameters

​Headers

​Response

​Request Example

​Response Examples

​Health Status Values

​Checking Health Before Scheduling

​Next Steps

List Integrations

Disconnect

Schedule Video

Dashboard

Authorizations

Path Parameters

Response

Overview

Endpoint

Path Parameters

Headers

Response

Request Example

Response Examples

Health Status Values

Checking Health Before Scheduling

Next Steps