The Contacts REST API provides complete CRUD operations for managing contact profiles and relationships. Contacts represent individuals or entities that your AI personas interact with across conversations.
Base URL: https://your-api-name.mercury.ratiomachina.com Authentication: x-mercury-api-key: YOUR_API_KEY
No query parameters supported. Returns all contacts.
{
"contacts": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "customer-john-smith",
"name": "John Smith",
"data": {
"email": "john.smith@example.com",
"phone": "+1-555-0123",
"company": "Tech Solutions Inc.",
"title": "CTO"
},
"createdAt": "2024-01-10T09:15:00Z",
"updatedAt": "2024-01-14T16:30:00Z"
}
]
}{
"externalId": "prospect-mary-davis",
"name": "Mary Davis",
"data": {
"email": "mary.davis@innovatetech.com",
"phone": "+1-555-0987",
"company": "InnovateTech Solutions",
"title": "VP of Engineering"
}
}{
"contact": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "prospect-mary-davis",
"name": "Mary Davis",
"data": {
"email": "mary.davis@innovatetech.com",
"phone": "+1-555-0987",
"company": "InnovateTech Solutions",
"title": "VP of Engineering"
},
"createdAt": "2024-01-15T11:30:00Z",
"updatedAt": "2024-01-15T11:30:00Z"
}
}external_id - Contact external IDNo query parameters supported.
{
"contact": {
"id": "uuid-contact-789",
"externalId": "prospect-mary-davis",
"name": "Mary Davis",
"email": "mary.davis@innovatetech.com",
"phone": "+1-555-0987",
"data": { ... },
"tags": ["enterprise", "qualified_lead"],
"status": "active",
"engagementMetrics": {
"totalConversations": 8,
"avgResponseTime": "4h 15m",
"lastEngagement": "2024-01-14T14:20:00Z",
"engagementScore": 78,
"preferredChannels": ["phone", "email"],
"topicInterests": [
{"topic": "compliance", "score": 0.89},
{"topic": "integration", "score": 0.76}
]
},
"recentConversations": [
{
"id": "uuid-conv-456",
"personaName": "Technical Sales Engineer",
"lastMessage": "Let's schedule a demo for next week",
"status": "active",
"createdAt": "2024-01-14T10:00:00Z"
}
],
"relationships": [
{
"type": "company",
"contactId": "uuid-contact-890",
"contactName": "David Chen",
"role": "colleague",
"relationship": "works_with"
}
],
"createdAt": "2024-01-10T11:30:00Z",
"updatedAt": "2024-01-14T14:20:00Z"
}
}Updates a contact. Supports partial updates - only provided fields will be modified.
{
"name": "Mary Davis-Johnson",
"data": {
"email": "mary.davis@innovatetech.com",
"phone": "+1-555-0987",
"company": "InnovateTech Solutions",
"title": "Senior VP of Engineering"
}
}{
"contact": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "prospect-mary-davis",
"name": "Mary Davis",
"data": {
"email": "mary.davis@innovatetech.com",
"phone": "+1-555-0987",
"company": "InnovateTech Solutions",
"title": "VP of Engineering"
},
"createdAt": "2024-01-10T11:30:00Z",
"updatedAt": "2024-01-15T13:45:00Z"
}
}⚠️ Warning: Deleting a contact will remove all associated conversation history and relationships. This action cannot be undone. Consider deactivating the contact instead.
external_id - Contact external IDNo query parameters supported.
{
"message": "Contact deleted successfully",
"deletedContact": {
"id": "uuid-contact-789",
"name": "Mary Davis-Johnson",
"externalId": "prospect-mary-davis"
},
"impactSummary": {
"conversationsAffected": 8,
"relationshipsRemoved": 3,
"tagsCleared": 3,
"dataArchived": true
}
}Delete multiple contacts by their external IDs. Contacts with existing conversations cannot be deleted.
{
"external_ids": [
"lead-robert-wilson",
"lead-lisa-garcia"
]
}{
"message": "2 contact(s) deleted successfully",
"deletedCount": 2,
"deletedContacts": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "lead-robert-wilson",
"name": "Robert Wilson"
},
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"externalId": "lead-lisa-garcia",
"name": "Lisa Garcia"
}
],
"notFound": []
}Archive multiple contacts by their external IDs instead of deleting them. Archived contacts retain all data.
{
"external_ids": [
"lead-robert-wilson",
"lead-lisa-garcia"
]
}{
"message": "2 contact(s) archived successfully",
"archived": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalId": "lead-robert-wilson",
"name": "Robert Wilson",
"archived": true
},
{
"id": "123e4567-e89b-12d3-a456-426614174001",
"externalId": "lead-lisa-garcia",
"name": "Lisa Garcia",
"archived": true
}
],
"archived_count": 2,
"already_archived_count": 0,
"not_found_count": 0
}