Import Integrations

Integration apps with Imports allow your app to not just receive data from OMI but also perform specific Imports within the OMI ecosystem. This guide will walk you through creating apps that can perform Imports like creating memories, adding memories, and more.

What Are Integration Imports?

Integration Imports are predefined capabilities that your app can perform within the OMI ecosystem. Unlike triggers (which respond to events), Imports allow your app to proactively create or modify data in OMI.

Currently supported Imports include:

Create Conversation: Generate new conversations in the user’s OMI account
Create Memories(Facts): Add specific memories (previously called facts) to the user’s knowledge base
Read Conversations: Access and read all conversations in the user’s OMI account
Read Memories: Access and read all memories in the user’s knowledge base

Prerequisites

Before building an integration with Imports, you should:

Understand the basics of OMI app development
Be familiar with integration apps
Have a server or endpoint that can make API requests to OMI

Setting Up an Integration with Imports

Step 1: Define Your App’s Purpose 🎯

Decide what Imports your app will perform and when. For example:

Will your app create conversations based on external events?
Will it respond to user interImports in your own service?
Will it run on a schedule to create periodic conversations?

Step 2: Create Your App in OMI

Open the OMI app on your device
Go to the Apps section and select “Create App”
Fill in the basic app information (name, description, etc.)
Under “App Capabilities”, select “External Integration”
In the External Integration section, select “Imports”
Choose the specific Imports your app will perform (e.g., “Create conversations”, “Create memories”)

Step 3: Generate API Keys

After creating your app, you’ll need to generate API keys to authenticate your requests:

Go to your app’s management page
Scroll down to the “API Keys” section
Click “Create Key”
Copy and securely store the generated key - you won’t be able to see it again!

Implementing the Create Conversation Import

The Create Conversation Import allows your app to programmatically create new conversations in a user’s OMI account.

API Endpoint

To create a memory, make a POST request to:

POST https://api.omi.me/v2/integrations/{app_id}/user/conversations?uid={user_id}

Where:

{app_id} is your app’s unique identifier
{user_id} is the OMI user ID for whom you’re creating the memory

Authentication

Include your API key in the request headers:

Authorization: Bearer sk_your_api_key_here

Important: The API key must be associated with the app specified in the URL path.

Request Body

The request body should be a JSON object with the following structure:

{
  "started_at": "2024-07-21T22:34:43.384323+00:00",
  "finished_at": "2024-07-21T22:35:43.384323+00:00",
  "text": "This is the full text content of the memory that will be processed.",
  "text_source": "audio_transcript",
  "text_source_spec": "phone_call",
  "language": "en",
  "geolocation": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Required Fields:

text: The full text content of the conversation

Optional Fields:

started_at: When the conversation/event started (ISO 8601 format) - defaults to current time if not provided
finished_at: When the conversation/event ended (ISO 8601 format) - defaults to started_at + 5 minutes if not provided
language: Language code (e.g., “en” for English) - defaults to “en” if not provided
geolocation: Location data for the conversation
- latitude: Latitude coordinate
- longitude: Longitude coordinate
text_source: Source of the text content (options: “audio_transcript”, “message”, “other_text”) - defaults to “audio_transcript”
text_source_spec: Additional specification about the source (optional)

Response

A successful request will return a 200 OK status with an empty response body:

{}

The conversation will be created asynchronously in the user’s account.

Error Handling

Common error responses include:

400 Bad Request: Invalid request format
401 Unauthorized: Missing or invalid Authorization header
403 Forbidden: Invalid API key, app not enabled for user, or app lacks create_conversation capability
404 Not Found: App not found
429 Too Many Requests: Rate limit exceeded

Implementing the Create Memories Import

The Create Memories Import allows your app to programmatically add memories to a user’s knowledge base in OMI.

API Endpoint

To create memories, make a POST request to:

POST https://api.omi.me/v2/integrations/{app_id}/user/memories?uid={user_id}

Where:

{app_id} is your app’s unique identifier
{user_id} is the OMI user ID for whom you’re creating the facts

Implementing the Read Conversations Import

The Read Conversations Import allows your app to programmatically access and read all conversations in a user’s OMI account.

API Endpoint

To read conversations, make a GET request to:

GET https://api.omi.me/v2/integrations/{app_id}/conversations?uid={user_id}

Where:

{app_id} is your app’s unique identifier
{user_id} is the OMI user ID whose conversations you want to access

Authentication

Include your API key in the request headers:

Authorization: Bearer sk_your_api_key_here

Important: The API key must be associated with the app specified in the URL path.

Query Parameters

The endpoint supports the following optional query parameters:

limit: Maximum number of conversations to return (default: 100, max: 1000)
offset: Number of conversations to skip (for pagination)
include_discarded: Whether to include discarded conversations (default: false)
statuses: Filter by conversation statuses (comma-separated list)

Response

A successful request will return a 200 OK status with a JSON response containing an array of conversations:

{
  "conversations": [
    {
      "id": "conversation_id_1",
      "created_at": "2024-03-15T12:00:00Z",
      "started_at": "2024-03-15T12:00:00Z",
      "finished_at": "2024-03-15T12:05:00Z",
      "text": "Full conversation text content...",
      "structured": {
        "title": "Conversation Title",
        "overview": "Brief overview of the conversation"
      },
      "transcript_segments": [
        {
          "text": "Segment text...",
          "start_time": 0,
          "end_time": 10
        }
      ],
      "geolocation": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    }
  ]
}

Error Handling

Common error responses include:

400 Bad Request: Invalid request format
401 Unauthorized: Missing or invalid Authorization header
403 Forbidden: Invalid API key, app not enabled for user, or app lacks read_conversations capability
404 Not Found: App not found
429 Too Many Requests: Rate limit exceeded

Implementing the Read Memories Import

The Read Memories Import allows your app to programmatically access and read all memories in a user’s knowledge base.

API Endpoint

To read memories, make a GET request to:

GET https://api.omi.me/v2/integrations/{app_id}/memories?uid={user_id}

Where:

{app_id} is your app’s unique identifier
{user_id} is the OMI user ID whose memories you want to access

Authentication

Include your API key in the request headers:

Authorization: Bearer sk_your_api_key_here

Important: The API key must be associated with the app specified in the URL path.

Query Parameters

The endpoint supports the following optional query parameters:

limit: Maximum number of memories to return (default: 100, max: 1000)
offset: Number of memories to skip (for pagination)

Response

A successful request will return a 200 OK status with a JSON response containing an array of memories:

{
  "memories": [
    {
      "id": "memory_id_1",
      "content": "User prefers vegetarian food options",
      "created_at": "2024-03-15T12:00:00Z",
      "tags": ["preferences", "food"]
    },
    {
      "id": "memory_id_2",
      "content": "User's anniversary is on June 12th",
      "created_at": "2024-03-15T12:05:00Z",
      "tags": ["dates", "personal"]
    }
  ]
}

Error Handling

Common error responses include:

400 Bad Request: Invalid request format
401 Unauthorized: Missing or invalid Authorization header
403 Forbidden: Invalid API key, app not enabled for user, or app lacks read_memories capability
404 Not Found: App not found
429 Too Many Requests: Rate limit exceeded

Authentication

Include your API key in the request headers:

Authorization: Bearer sk_your_api_key_here

Important: The API key must be associated with the app specified in the URL path.

Request Body

The request body should be a JSON object with the following structure:

{
  "text": "The text from which memories will be extracted. This could be information about preferences, important dates, or other factual information.",
  "text_source": "email",
  "text_source_spec": "newsletter",
  "memories": [
    {
      "content": "User prefers vegetarian food options",
      "tags": ["preferences", "food"]
    },
    {
      "content": "User's anniversary is on June 12th",
      "tags": ["dates", "personal"]
    }
  ]
}

Required Fields:

Either text or memories must be provided:

text: The text content from which memories will be extracted
memories: An array of explicit memory objects to be created directly

Optional Fields:

text_source: Source of the text content (options: “email”, “social_post”, “other”) - defaults to “other”
text_source_spec: Additional specification about the source (optional)
For each memory in the memories array:
- content: The content of the memory (required)
- tags: Array of tags associated with the memory (optional)

Response

A successful request will return a 200 OK status with an empty response body:

{}

The memories will be extracted and saved asynchronously in the user’s account.

Error Handling

Common error responses include:

400 Bad Request: Invalid request format
401 Unauthorized: Missing or invalid Authorization header
403 Forbidden: Invalid API key, app not enabled for user, or app lacks create_memories capability
404 Not Found: App not found
422 Unprocessable Entity: Either text or explicit memories are required and cannot be empty
429 Too Many Requests: Rate limit exceeded

Best Practices

User Consent: Always ensure you have user consent before creating conversations or memories on their behalf
Rate Limiting: Implement rate limiting in your app to avoid hitting API limits
Error Handling: Implement robust error handling for API requests
Data Quality: Ensure the content is well-formatted and contains meaningful information
Meaningful Content: Only create memories and facts with meaningful content that provides value to users
Verify App Enablement: Check that users have enabled your app before attempting to create content
Proper Authentication: Securely store and use your API keys
Structured Data: When possible, provide well-structured data to improve the quality of extracted information

Example Implementation

Here are examples showing how to create and read memories, facts, and conversations:

Reading Conversations

Python Example

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/conversations"

# Optional query parameters
params = {
    "limit": 50,
    "offset": 0,
    "include_discarded": False
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    params=params
)

# Handle the response
if response.status_code == 200:
    conversations = response.json()["conversations"]
    print(f"Retrieved {len(conversations)} conversations")
    for conversation in conversations:
        print(f"Conversation ID: {conversation['id']}")
        print(f"Title: {conversation['structured']['title']}")
        print(f"Created at: {conversation['created_at']}")
        print("---")
else:
    print(f"Error retrieving conversations: {response.status_code}")
    print(response.text)

cURL Example

curl -X GET "https://api.omi.me/v2/integrations/your_app_id_here/conversations?uid=user_123&limit=50&offset=0" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json"

Reading Memories

Python Example

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/memories"

# Optional query parameters
params = {
    "limit": 100,
    "offset": 0
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    params=params
)

# Handle the response
if response.status_code == 200:
    memories = response.json()["memories"]
    print(f"Retrieved {len(memories)} memories")
    for memory in memories:
        print(f"Memory ID: {memory['id']}")
        print(f"Content: {memory['content']}")
        print(f"Created at: {memory['created_at']}")
        if memory.get('tags'):
            print(f"Tags: {', '.join(memory['tags'])}")
        print("---")
else:
    print(f"Error retrieving memories: {response.status_code}")
    print(response.text)

cURL Example

curl -X GET "https://api.omi.me/v2/integrations/your_app_id_here/memories?uid=user_123&limit=100&offset=0" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json"

Creating Conversations

Example 1: Audio Transcript Conversation

Python Example

import requests
import json
from datetime import datetime, timezone

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations"

# Audio transcript conversation data
conversation_data = {
    "started_at": datetime.now(timezone.utc).isoformat(),
    "finished_at": datetime.now(timezone.utc).isoformat(),
    "language": "en",
    "text": "John: Hi Sarah, how was your weekend?\n\nSarah: It was great! I went hiking at Mount Rainier.\n\nJohn: That sounds amazing. I've been wanting to go there.\n\nSarah: You should definitely check it out. The views are breathtaking.",
    "text_source": "audio_transcript",
    "text_source_spec": "phone_call"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(conversation_data)
)

# Handle the response
if response.status_code == 200:
    print("Conversation created successfully")
else:
    print(f"Error creating conversation: {response.status_code}")
    print(response.text)

cURL Example

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/conversations?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2024-03-10T15:00:00.000Z",
    "finished_at": "2024-03-10T15:05:00.000Z",
    "language": "en",
    "text": "John: Hi Sarah, how was your weekend?\n\nSarah: It was great! I went hiking at Mount Rainier.\n\nJohn: That sounds amazing. I'\''ve been wanting to go there.\n\nSarah: You should definitely check it out. The views are breathtaking.",
    "text_source": "audio_transcript",
    "text_source_spec": "phone_call"
  }'

Example 2: Other Text Conversation

Python Example

import requests
import json
from datetime import datetime, timezone

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations"

# Other text conversation data
conversation_data = {
    "started_at": datetime.now(timezone.utc).isoformat(),
    "finished_at": datetime.now(timezone.utc).isoformat(),
    "language": "en",
    "text": "From: alex@example.com\nTo: me@example.com\nSubject: Dinner Plans\n\nHi there,\n\nWould you like to grab dinner this Friday at 7pm? I found a new restaurant downtown that has great reviews.\n\nLet me know if you're available!\n\nBest,\nAlex",
    "text_source": "other_text",
    "text_source_spec": "email"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(conversation_data)
)

# Handle the response
if response.status_code == 200:
    print("Conversation created successfully")
else:
    print(f"Error creating conversation: {response.status_code}")
    print(response.text)

cURL Example

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/conversations?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2024-03-10T15:00:00.000Z",
    "finished_at": "2024-03-10T15:05:00.000Z",
    "language": "en",
    "text": "From: alex@example.com\nTo: me@example.com\nSubject: Dinner Plans\n\nHi there,\n\nWould you like to grab dinner this Friday at 7pm? I found a new restaurant downtown that has great reviews.\n\nLet me know if you'\''re available!\n\nBest,\nAlex",
    "text_source": "other_text",
    "text_source_spec": "email"
  }'

Example 3: Other Text Conversation with Location

Python Example

import requests
import json
from datetime import datetime, timezone

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations"

# Other text conversation data with location
conversation_data = {
    "started_at": datetime.now(timezone.utc).isoformat(),
    "finished_at": datetime.now(timezone.utc).isoformat(),
    "language": "en",
    "text": "Just finished my first marathon! 26.2 miles in 4 hours and 15 minutes. So proud of this accomplishment after 6 months of training. #running #marathon #personalgoals",
    "text_source": "other_text",
    "text_source_spec": "social_post",
    "geolocation": {
        "latitude": 40.7128,
        "longitude": -74.0060
    }
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(conversation_data)
)

# Handle the response
if response.status_code == 200:
    print("Conversation created successfully")
else:
    print(f"Error creating conversation: {response.status_code}")
    print(response.text)

cURL Example

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/conversations?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2024-03-10T15:00:00.000Z",
    "finished_at": "2024-03-10T15:05:00.000Z",
    "language": "en",
    "text": "Just finished my first marathon! 26.2 miles in 4 hours and 15 minutes. So proud of this accomplishment after 6 months of training. #running #marathon #personalgoals",
    "text_source": "other_text",
    "text_source_spec": "social_post",
    "geolocation": {
        "latitude": 40.7128,
        "longitude": -74.0060
    }
  }'

Example 4: Message Conversation

Python Example

import requests
import json
from datetime import datetime, timezone

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations"

# Message conversation data
conversation_data = {
    "started_at": datetime.now(timezone.utc).isoformat(),
    "finished_at": datetime.now(timezone.utc).isoformat(),
    "language": "en",
    "text": "Mom: Don't forget to pick up milk on your way home\n\nMe: Will do. Need anything else?\n\nMom: Maybe some bread too if the store has the whole grain kind\n\nMe: Got it. I'll be home around 6pm",
    "text_source": "message",
    "text_source_spec": "sms"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(conversation_data)
)

# Handle the response
if response.status_code == 200:
    print("Conversation created successfully")
else:
    print(f"Error creating conversation: {response.status_code}")
    print(response.text)

cURL Example

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/conversations?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "started_at": "2024-03-10T15:00:00.000Z",
    "finished_at": "2024-03-10T15:05:00.000Z",
    "language": "en",
    "text": "Mom: Don'\''t forget to pick up milk on your way home\n\nMe: Will do. Need anything else?\n\nMom: Maybe some bread too if the store has the whole grain kind\n\nMe: Got it. I'\''ll be home around 6pm",
    "text_source": "message",
    "text_source_spec": "sms"
  }'

Creating Memories

Example: Creating Memories from Different Sources

Python Example - Email Memories

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories"

# Memories data from email
memories_data = {
    "text": "Your flight to Paris has been confirmed for May 15th, 2024. Departure: JFK at 9:30 PM. Arrival: CDG at 11:00 AM local time. Confirmation code: ABC123. Your hotel reservation at Hotel de Paris is confirmed for May 16-20, 2024.",
    "text_source": "email",
    "text_source_spec": "travel_confirmation"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(memories_data)
)

# Handle the response
if response.status_code == 200:
    print("Memories created successfully")
else:
    print(f"Error creating memories: {response.status_code}")
    print(response.text)

cURL Example - Email Memories

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/memories?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your flight to Paris has been confirmed for May 15th, 2024. Departure: JFK at 9:30 PM. Arrival: CDG at 11:00 AM local time. Confirmation code: ABC123. Your hotel reservation at Hotel de Paris is confirmed for May 16-20, 2024.",
    "text_source": "email",
    "text_source_spec": "travel_confirmation"
  }'

Python Example - Social Post Memories

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories"

# Memories data from social post
memories_data = {
    "text": "I'm excited to announce that I've accepted a new position as Senior Software Engineer at TechCorp starting next month! Looking forward to this new chapter in my career. #newjob #softwareengineering #career",
    "text_source": "social_post",
    "text_source_spec": "linkedin"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(memories_data)
)

# Handle the response
if response.status_code == 200:
    print("Memories created successfully")
else:
    print(f"Error creating memories: {response.status_code}")
    print(response.text)

cURL Example - Social Post Memories

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/memories?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "I'\''m excited to announce that I'\''ve accepted a new position as Senior Software Engineer at TechCorp starting next month! Looking forward to this new chapter in my career. #newjob #softwareengineering #career",
    "text_source": "social_post",
    "text_source_spec": "linkedin"
  }'

Python Example - Other Memories

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories"

# Memories data from other source
memories_data = {
    "text": "Dr. Smith's contact information: Phone: (555) 123-4567, Email: dr.smith@hospital.org. Next appointment scheduled for April 3rd at 2:30 PM. Remember to bring your insurance card and list of current medications.",
    "text_source": "other",
    "text_source_spec": "health_app"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(memories_data)
)

# Handle the response
if response.status_code == 200:
    print("Memories created successfully")
else:
    print(f"Error creating memories: {response.status_code}")
    print(response.text)

Python Example - Explicit Memories

import requests
import json

# API configuration
APP_ID = "your_app_id_here"
API_KEY = "sk_your_api_key_here"
USER_ID = "user_123"
API_URL = f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories"

# Explicit memories data
memories_data = {
    "memories": [
        {
            "content": "User is allergic to peanuts and shellfish",
            "tags": ["health", "allergies", "important"]
        },
        {
            "content": "User's mother's birthday is on August 15th",
            "tags": ["family", "dates", "birthday"]
        },
        {
            "content": "User prefers window seats when flying",
            "tags": ["preferences", "travel"]
        }
    ],
    "text_source": "other",
    "text_source_spec": "user_profile"
}

# Make the API request
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{API_URL}?uid={USER_ID}",
    headers=headers,
    data=json.dumps(memories_data)
)

# Handle the response
if response.status_code == 200:
    print("Explicit memories created successfully")
else:
    print(f"Error creating memories: {response.status_code}")
    print(response.text)

cURL Example - Other Memories

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/memories?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Dr. Smith'\''s contact information: Phone: (555) 123-4567, Email: dr.smith@hospital.org. Next appointment scheduled for April 3rd at 2:30 PM. Remember to bring your insurance card and list of current medications.",
    "text_source": "other",
    "text_source_spec": "health_app"
  }'

cURL Example - Explicit Memories

curl -X POST "https://api.omi.me/v2/integrations/your_app_id_here/user/memories?uid=user_123" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {
        "content": "User is allergic to peanuts and shellfish",
        "tags": ["health", "allergies", "important"]
      },
      {
        "content": "User'\''s mother'\''s birthday is on August 15th",
        "tags": ["family", "dates", "birthday"]
      },
      {
        "content": "User prefers window seats when flying",
        "tags": ["preferences", "travel"]
      }
    ],
    "text_source": "other",
    "text_source_spec": "user_profile"
  }'

Testing Your Integration

To test your integration:

Use a development API key
Create test conversations with clearly marked test content
Verify the conversations appear in the user’s OMI app
Check that the structured data (title, overview, Import items) appears correctly

Troubleshooting

Common issues and solutions:

Authentication Errors: Double-check your API key and ensure it’s being sent correctly in the Authorization header
Invalid Request Format: Validate your JSON against the required schema
App Not Found: Verify your app ID is correct
Permission Errors: Ensure your app has the create_conversation capability and is enabled for the user
Rate Limiting: If you receive a 429 error, implement exponential backoff in your requests
Missing Required Fields: Ensure you’re providing text, text_source

Prerequisites for Using Integration Imports

Before your app can use integration Imports, several conditions must be met:

App Configuration: Your app must be configured with the “External Integration” capability and specifically have the appropriate Import enabled:
- For creating conversations: the “create_conversation” Import
- For creating memories: the “create_memories” Import
- For reading conversations: the “read_conversations” Import
- For reading memories: the “read_memories” Import
API Key: You must generate an API key for your app through the app management interface.
User Enablement: The user must have explicitly enabled your app in their OMI account.
Authorization: Your API requests must include the proper Authorization header with your API key.

If any of these conditions are not met, the API will return appropriate error responses.

Future Imports

The OMI team is continuously working to expand the available Imports. Future Imports may include:

Updating existing conversations
Updating existing memories
Setting reminders
Accessing and updating user preferences
And more!

Stay tuned to the documentation for updates on new Import capabilities.

Submitting Your App

Once your integration with Imports is ready:

Test thoroughly with real-world scenarios
Create clear setup instructions for users
Submit your app through the OMI mobile app
Include details about what Imports your app performs and when

For more details on the submission process, see the Submitting Apps guide.

Example Use Cases

Here are some inspiring examples of what you can build with integration Imports:

Journal Creator: Automatically create conversation entries based on data from a journaling app
Meeting Summarizer: Create conversations with structured summaries after calendar meetings
Health Tracker: Generate conversations with health insights based on fitness tracker data
Social Media Archiver: Create conversations from important social media interImports
Learning Assistant: Create structured conversations from educational content consumption
Preference Tracker: Extract memories about user preferences from emails or messages
Knowledge Base Builder: Create memories from educational content or research materials
Contact Information Manager: Extract contact details as memories from emails or messages
Personal Analytics Dashboard: Read and analyze conversations and memories to provide insights
Memory Search Tool: Create a specialized search interface for user memories
Conversation Visualizer: Generate visual representations of conversation patterns and topics
Cross-Platform Sync: Read conversations from OMI and sync them with other platforms

We can’t wait to see what you build with OMI integration Imports!

Get Started

Developer

Hardware

DIY Guide

Info

​Import Integrations

​What Are Integration Imports?

​Prerequisites

​Setting Up an Integration with Imports

​Step 1: Define Your App’s Purpose 🎯

​Step 2: Create Your App in OMI

​Step 3: Generate API Keys

​Implementing the Create Conversation Import

​API Endpoint

​Authentication

​Request Body

​Required Fields:

​Optional Fields:

​Response

​Error Handling

​Implementing the Create Memories Import

​API Endpoint

​Implementing the Read Conversations Import

​API Endpoint

​Authentication

​Query Parameters

​Response

​Error Handling

​Implementing the Read Memories Import

​API Endpoint

​Authentication

​Query Parameters

​Response

​Error Handling

​Authentication

​Request Body

​Required Fields:

​Optional Fields:

​Response

​Error Handling

​Best Practices

​Example Implementation

​Reading Conversations

​Python Example

cURL Example

​Reading Memories

​Python Example

cURL Example

​Creating Conversations

​Example 1: Audio Transcript Conversation

Python Example

cURL Example

​Example 2: Other Text Conversation

Python Example

cURL Example

​Example 3: Other Text Conversation with Location

Python Example

cURL Example

​Example 4: Message Conversation

Python Example

cURL Example

​Creating Memories

​Example: Creating Memories from Different Sources

Python Example - Email Memories

cURL Example - Email Memories

Python Example - Social Post Memories

cURL Example - Social Post Memories

Python Example - Other Memories

Python Example - Explicit Memories

cURL Example - Other Memories

cURL Example - Explicit Memories

​Testing Your Integration

​Troubleshooting

​Prerequisites for Using Integration Imports

​Future Imports

​Submitting Your App

​Example Use Cases

Import Integrations

What Are Integration Imports?

Prerequisites

Setting Up an Integration with Imports

Step 1: Define Your App’s Purpose 🎯

Step 2: Create Your App in OMI

Step 3: Generate API Keys

Implementing the Create Conversation Import

API Endpoint

Authentication

Request Body

Required Fields:

Optional Fields:

Response

Error Handling

Implementing the Create Memories Import

API Endpoint

Implementing the Read Conversations Import

API Endpoint

Authentication

Query Parameters

Response

Error Handling

Implementing the Read Memories Import

API Endpoint

Authentication

Query Parameters

Response

Error Handling

Authentication

Request Body

Required Fields:

Optional Fields:

Response

Error Handling

Best Practices

Example Implementation

Reading Conversations

Python Example

Reading Memories

Python Example

Creating Conversations

Example 1: Audio Transcript Conversation

Example 2: Other Text Conversation

Example 3: Other Text Conversation with Location

Example 4: Message Conversation

Creating Memories

Example: Creating Memories from Different Sources

Testing Your Integration

Troubleshooting

Prerequisites for Using Integration Imports

Future Imports

Submitting Your App

Example Use Cases