API Overview

ULink provides SDK API endpoints specifically designed for mobile app integration. This API enables you to create and manage links, track app installations and user sessions, and handle deep linking from within your mobile applications. Our SDK API is optimized for mobile development workflows with Flutter SDK support and additional platform SDKs coming soon.

Getting Started

Prerequisites

ULink Account: Sign up at the ULink Dashboard
Project Setup: Create a project to organize your links
API Key: Generate an API key from your project's API Keys section

Quick Start Example

terminal
# Create your first link via API
curl -X POST https://api.ulink.ly/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First API Link",
    "type": "unified",
    "fallbackUrl": "https://mywebsite.com",
    "iosUrl": "https://apps.apple.com/app/myapp",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp"
  }'

API Fundamentals

Base URL

All API requests should be made to:

base-url

https://api.ulink.ly/v1

Authentication

ULink uses API key authentication with Bearer token format:

authorization-header

Authorization: Bearer your-api-key-here

Getting Your API Key

Navigate to your project dashboard
Go to API Keys section
Click "Create API Key"
Provide a descriptive name
Copy the generated key (store it securely!)

API Key Security

Security Warning

Never expose API keys in client-side code or commit them to version control. This could lead to unauthorized access to your ULink account.

Best Practices

Use environment variables for server-side applications
Rotate keys regularly for enhanced security
Use project-specific keys to limit scope

Request Headers

All requests should include these headers:

request-headers
Authorization: Bearer your-api-key-here
Content-Type: application/json
User-Agent: YourApp/1.0

Response Format

All API responses follow a consistent JSON structure:

Success Response

success-response
{
  "success": true,
  "data": {
    "id": "link_123456",
    "name": "Summer Campaign",
    "shortUrl": "https://ulink.ly/summer",
    "createdAt": "2024-03-15T10:30:00Z"
  },
  "message": "Link created successfully"
}

Error Response

error-response
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": {
      "field": "fallbackUrl",
      "issue": "URL format is invalid",
      "provided": "not-a-url"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`INTERNAL_ERROR`	500	Server error

SDK API Endpoints

SDK-Specific Endpoints

These endpoints are optimized for mobile SDK usage and use X-App-Key header instead of Authorization: Bearer for authentication.

Links Management

The SDK API provides endpoints for creating and managing links programmatically from your mobile applications.

Create Link

create-link-endpoint

POST /sdk/links

Headers:

sdk-headers

X-App-Key: your-api-key-here
Content-Type: application/json

Request Body:

create-link-request
{
  "type": "unified", // or "dynamic"
  "slug": "custom-slug", // optional
  "fallbackUrl": "https://mywebsite.com",
  "iosUrl": "https://apps.apple.com/app/myapp", // for unified links
  "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp", // for unified links
  "iosFallbackUrl": "https://mywebsite.com/ios", // for dynamic links
  "androidFallbackUrl": "https://mywebsite.com/android", // for dynamic links
  "parameters": { // for dynamic links
    "screen": "product",
    "productId": "123"
  },
  "metadata": {
    "campaign": "summer-sale"
  }
}

Response:

create-link-response
{
  "id": "link-id",
  "slug": "custom-slug",
  "shortUrl": "https://yourdomain.com/custom-slug",
  "type": "unified",
  "fallbackUrl": "https://mywebsite.com",
  "createdAt": "2024-01-01T00:00:00Z"
}

Get Link by Slug

get-link-endpoint

GET /sdk/links/{slug}

Response:

get-link-response
{
  "id": "link-id",
  "slug": "custom-slug",
  "type": "unified",
  "fallbackUrl": "https://mywebsite.com",
  "iosUrl": "https://apps.apple.com/app/myapp",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp"
}

Resolve Link

resolve-link-endpoint

GET /sdk/resolve?url=https://yourdomain.com/custom-slug

Response:

resolve-link-response
{
  "id": "link-id",
  "slug": "custom-slug",
  "type": "unified",
  "fallbackUrl": "https://mywebsite.com",
  "iosUrl": "https://apps.apple.com/app/myapp",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp",
  "parameters": {
    "screen": "product",
    "productId": "123"
  }
}

Installation Tracking

Track Installation

track-installation-endpoint

POST /sdk/installations/track

Headers:

sdk-headers

X-App-Key: your-api-key-here
Content-Type: application/json

Request Body:

track-installation-request
{
  "installationId": "unique-installation-id",
  "deviceId": "device-identifier",
  "deviceModel": "iPhone 15 Pro",
  "deviceManufacturer": "Apple",
  "osName": "iOS",
  "osVersion": "17.0",
  "appVersion": "1.0.0",
  "appBuild": "100",
  "language": "en",
  "timezone": "America/New_York",
  "metadata": {
    "source": "app-store"
  }
}

Response:

track-installation-response
{
  "success": true,
  "installationId": "installation-record-id",
  "isNew": true
}

Session Tracking

Start Session

start-session-endpoint

POST /sdk/sessions/start

Headers:

sdk-headers

X-App-Key: your-api-key-here
Content-Type: application/json

Request Body:

start-session-request
{
  "installationId": "unique-installation-id",
  "deviceOrientation": "portrait",
  "networkType": "wifi",
  "batteryLevel": 85,
  "isCharging": false,
  "metadata": {
    "screen": "home"
  }
}

Response:

start-session-response
{
  "success": true,
  "sessionId": "session-id"
}

End Session

end-session-endpoint

POST /sdk/sessions/{sessionId}/end

Headers:

end-session-headers

X-App-Key: your-api-key-here

Response:

end-session-response
{
  "success": true
}

SDK Examples

Creating Links via SDK API

Unified Link Example

unified-link-example
curl -X POST https://api.ulink.ly/sdk/links \
  -H "X-App-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "unified",
    "slug": "product-launch",
    "fallbackUrl": "https://mywebsite.com/product",
    "iosUrl": "https://apps.apple.com/app/myapp/id123456",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.myapp",
    "metadata": {
      "campaign": "product_launch_2024"
    }
  }'

Dynamic Link Example

dynamic-link-example
curl -X POST https://api.ulink.ly/sdk/links \
  -H "X-App-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dynamic",
    "fallbackUrl": "https://mywebsite.com/signup",
    "iosFallbackUrl": "https://mywebsite.com/ios",
    "androidFallbackUrl": "https://mywebsite.com/android",
    "parameters": {
      "userId": "12345",
      "screen": "referral"
    }
  }'

Resolving Links

resolve-link-example

curl -X GET "https://api.ulink.ly/sdk/resolve?url=https://yourdomain.com/product-launch"

Tracking Installation

track-installation-example
curl -X POST https://api.ulink.ly/sdk/installations/track \
  -H "X-App-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "installationId": "unique-installation-id",
    "deviceId": "device-identifier",
    "deviceModel": "iPhone 15 Pro",
    "deviceManufacturer": "Apple",
    "osName": "iOS",
    "osVersion": "17.0",
    "appVersion": "1.0.0",
    "language": "en"
  }'

Starting a Session

start-session-example
curl -X POST https://api.ulink.ly/sdk/sessions/start \
  -H "X-App-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "installationId": "unique-installation-id",
    "deviceOrientation": "portrait",
    "networkType": "wifi"
  }'

Best Practices

Security

API Key Management

Store API keys securely using environment variables
Never commit API keys to version control
Rotate keys regularly for enhanced security
Use the X-App-Key header for SDK authentication

Request Validation

Always validate URLs before sending to the SDK API
Implement proper error handling for all API calls
Use HTTPS for all requests to ensure secure communication

Performance

Caching and Optimization
- Cache link resolution responses when appropriate
- Batch session tracking when possible
- Minimize unnecessary API calls
Session Management
- Always end sessions properly to avoid resource leaks
- Track installations only once per unique installation
- Use appropriate session timeouts

Error Handling

error-handling-example
try {
  const response = await ulinkSDK.createUnifiedLink(linkData);
  return response;
} catch (error) {
  if (error.response?.status === 400) {
    // Validation error - check request data
    console.error('Validation error:', error.response.data.message);
  } else {
    // Other errors
    console.error('SDK API error:', error.response?.data?.message);
  }
  throw error;
}

Troubleshooting

Common Issues

401 Unauthorized

Cause: Invalid or missing API key in X-App-Key header

Solution: Verify your API key is correct and properly formatted in the header

400 Bad Request

Cause: Invalid request parameters for SDK endpoints

Solution: Check the error details for specific validation issues

404 Not Found

Cause: Link slug doesn't exist or session not found

Solution: Verify the slug or session ID and your permissions

Debugging Tips

Enable Request Logging

request-logging
// Log all SDK requests for debugging
axios.interceptors.request.use(request => {
  console.log('SDK Request:', request.url, request.data);
  return request;
});

Validate SDK Request Data

validate-request-data
// Ensure required fields are present for link creation
const requiredFields = ['slug', 'type', 'fallbackUrl'];
const missingFields = requiredFields.filter(field => !linkData[field]);
if (missingFields.length > 0) {
  throw new Error(`Missing required fields: ${missingFields.join(', ')}`);
}

SDK Integration

This API is designed for SDK integration. For mobile app development, use our official SDKs:

Flutter SDK - For Flutter applications
Coming Soon - iOS, Android, React Native, and Web SDKs

Support

Need help with the SDK API? Here are your options:

Issues: Report bugs or request features on GitHub Issues
Contact: Get in touch through our contact form

Ready to start building? Get your API key from the ULink Dashboard and begin integrating with our SDK API!

Getting Started​

Prerequisites​

Quick Start Example​

API Fundamentals​

Base URL​

Authentication​

Getting Your API Key​

API Key Security​

Request Headers​

Response Format​

Success Response​

Error Response​

Error Codes​

SDK API Endpoints​

Links Management​

Create Link​

Get Link by Slug​

Resolve Link​

Installation Tracking​

Track Installation​

Session Tracking​

Start Session​

End Session​

SDK Examples​

Creating Links via SDK API​

Unified Link Example​

Dynamic Link Example​

Resolving Links​

Tracking Installation​

Starting a Session​

Best Practices​

Security​

Performance​

Error Handling​

Troubleshooting​

Common Issues​

Debugging Tips​

SDK Integration​

Support​

Getting Started

Prerequisites

Quick Start Example

API Fundamentals

Base URL

Authentication

Getting Your API Key

API Key Security

Request Headers

Response Format

Success Response

Error Response

Error Codes

SDK API Endpoints

Links Management

Create Link

Get Link by Slug

Resolve Link

Installation Tracking

Track Installation

Session Tracking

Start Session

End Session

SDK Examples

Creating Links via SDK API

Unified Link Example

Dynamic Link Example

Resolving Links

Tracking Installation

Starting a Session

Best Practices

Security

Performance

Error Handling

Troubleshooting

Common Issues

Debugging Tips

SDK Integration

Support