Contacts API - GoBlue Documentation

Overview

The Contacts API provides comprehensive access to your contact database, allowing you to retrieve, update, and manage contact information generated through your GoBlue forms. Contacts are automatically created when webhook data is received with a phone number.

Base URL

https://api.goblue.app/v1/contacts

Authentication

All Contacts API endpoints require authentication via API key. See Authentication for details.

Contact Object

Properties

string

required

Unique identifier for the contact (UUID format)

firstName

string

Contact’s first name

lastName

string

Contact’s last name

phoneNumber

string

required

Contact’s phone number (normalized format)

string

Contact’s email address

status

string

required

Contact status: new, contacted, responded, converted

formId

string

required

ID of the form that created this contact

formName

string

required

Name of the form that created this contact

customFields

object

Additional data from webhook submissions

tags

array

Array of tags assigned to this contact

lastContactedAt

string

ISO timestamp when contact was last messaged

lastResponseAt

string

ISO timestamp when contact last responded (manually tracked)

messageCount

number

required

Total number of messages sent to this contact

source

string

Original source of the contact (if provided in webhook data)

notes

string

Internal notes about this contact

createdAt

string

required

ISO timestamp when contact was created

updatedAt

string

required

ISO timestamp when contact was last updated

Example Contact Object

{
  "id": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "phoneNumber": "+1234567890",
  "email": "[email protected]",
  "status": "contacted",
  "formId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "formName": "Website Contact Form",
  "customFields": {
    "companyName": "TechStart Inc",
    "serviceType": "web development",
    "budget": "$10,000-$25,000",
    "timeline": "Q2 2024",
    "jobTitle": "Marketing Director"
  },
  "tags": ["high-priority", "enterprise"],
  "lastContactedAt": "2024-01-15T14:30:00Z",
  "lastResponseAt": null,
  "messageCount": 2,
  "source": "google-ads",
  "notes": "Interested in custom e-commerce solution",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Endpoints

List All Contacts

Retrieve all contacts in your account with optional filtering and pagination.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.goblue.app/v1/contacts?page=1&limit=50"

Query Parameters:

page

number

default:"1"

Page number for pagination

limit

number

default:"50"

Number of contacts per page (max: 100)

status

string

Filter by status: new, contacted, responded, converted

formId

string

Filter by form ID

string

Search by name, phone, or email

tags

string

Filter by tags (comma-separated)

createdAfter

string

Filter contacts created after this date (ISO format)

createdBefore

string

Filter contacts created before this date (ISO format)

sortBy

string

default:"createdAt"

Sort field: createdAt, updatedAt, firstName, lastName

sortOrder

string

default:"desc"

Sort order: asc or desc

Response:

{
  "status": "success",
  "data": {
    "contacts": [
      {
        "id": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
        "firstName": "Sarah",
        "lastName": "Johnson",
        "phoneNumber": "+1234567890",
        "email": "[email protected]",
        "status": "contacted",
        "formName": "Website Contact Form",
        "messageCount": 2,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "total": 1247,
      "page": 1,
      "limit": 50,
      "totalPages": 25
    }
  }
}

Get Contact by ID

Retrieve a specific contact by its ID.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.goblue.app/v1/contacts/c47ac10b-58cc-4372-a567-0e02b2c3d479

Response:

{
  "status": "success",
  "data": {
    "contact": {
      "id": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
      "firstName": "Sarah",
      "lastName": "Johnson",
      "phoneNumber": "+1234567890",
      "email": "[email protected]",
      "status": "contacted",
      "formId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "formName": "Website Contact Form",
      "customFields": {
        "companyName": "TechStart Inc",
        "serviceType": "web development"
      },
      "tags": ["high-priority"],
      "messageCount": 2,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  }
}

Update Contact

Update a contact’s information, status, or custom fields.

curl -X PUT https://api.goblue.app/v1/contacts/c47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "responded",
    "lastResponseAt": "2024-01-15T16:45:00Z",
    "notes": "Customer called back interested in premium package",
    "tags": ["high-priority", "enterprise", "hot-lead"]
  }'

Request Body (all fields optional):

firstName

string

Update contact’s first name

lastName

string

Update contact’s last name

string

Update contact’s email address

status

string

Update contact status: new, contacted, responded, converted

customFields

object

Update or add custom field data

tags

array

Replace existing tags with this array

notes

string

Update internal notes

lastResponseAt

string

Set timestamp when contact last responded (ISO format)

Response:

{
  "status": "success",
  "data": {
    "contact": {
      "id": "c47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "responded",
      "notes": "Customer called back interested in premium package",
      "tags": ["high-priority", "enterprise", "hot-lead"],
      "lastResponseAt": "2024-01-15T16:45:00Z",
      "updatedAt": "2024-01-15T16:50:00Z"
    }
  }
}

Delete Contact

Delete a contact and all associated message history.

This action is irreversible. All message history and data for this contact will be permanently deleted.

curl -X DELETE https://api.goblue.app/v1/contacts/c47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "message": "Contact deleted successfully",
  "data": {
    "deletedId": "c47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

Get Contact Messages

Retrieve all messages sent to a specific contact.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.goblue.app/v1/contacts/c47ac10b-58cc-4372-a567-0e02b2c3d479/messages

Response:

{
  "status": "success",
  "data": {
    "messages": [
      {
        "id": "m47ac10b-58cc-4372-a567-0e02b2c3d479",
        "content": "Hi Sarah, thanks for your interest in web development!",
        "status": "sent",
        "sentAt": "2024-01-15T14:30:00Z",
        "formName": "Website Contact Form"
      }
    ],
    "total": 2
  }
}

Bulk Update Contacts

Update multiple contacts at once.

curl -X PUT https://api.goblue.app/v1/contacts/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "c47ac10b-58cc-4372-a567-0e02b2c3d479",
      "c58bd21c-69dd-5483-b678-1f13c3d4e580"
    ],
    "updates": {
      "tags": ["campaign-q1-2024"],
      "customFields": {
        "campaign": "Q1 Promotion"
      }
    }
  }'

Response:

{
  "status": "success",
  "data": {
    "updated": 2,
    "errors": []
  }
}

Export Contacts

Export contacts data in various formats.

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.goblue.app/v1/contacts/export?format=csv&status=contacted"

Query Parameters:

format

string

default:"json"

Export format: json, csv, xlsx

status

string

Filter by contact status

formId

string

Filter by form ID

tags

string

Filter by tags (comma-separated)

fields

string

Specify fields to export (comma-separated)

Contact Status Workflow

Status Transitions

new → contacted

Automatic: When message is sent via iOS Shortcuts Manual: Update via API when manually contacting

await updateContact(contactId, {
  status: 'contacted',
  lastContactedAt: new Date().toISOString()
});

contacted → responded

Manual Only: Update when contact responds to message

await updateContact(contactId, {
  status: 'responded',
  lastResponseAt: new Date().toISOString(),
  notes: 'Customer replied showing interest'
});

responded → converted

Manual Only: Update when contact becomes customer

await updateContact(contactId, {
  status: 'converted',
  customFields: {
    ...existingFields,
    conversionDate: new Date().toISOString(),
    conversionValue: '$5000'
  }
});

Status Analytics

Get analytics on contact status distribution:

async function getContactAnalytics() {
  const response = await fetch('https://api.goblue.app/v1/contacts/analytics', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  
  return response.json();
}

// Response example:
{
  "statusDistribution": {
    "new": 156,
    "contacted": 487,
    "responded": 89,
    "converted": 32
  },
  "conversionRate": 4.2,
  "averageTimeToResponse": "2.3 hours",
  "topPerformingForms": [...]
}

Custom Fields

Dynamic Field Handling

GoBlue automatically creates custom fields based on webhook data:

// Webhook payload
{
  "firstName": "John",
  "phoneNumber": "+1234567890",
  "companySize": "50-100 employees",
  "industry": "SaaS",
  "budget": "$10,000+",
  "urgency": "high"
}

// Resulting contact custom fields
{
  "customFields": {
    "companySize": "50-100 employees",
    "industry": "SaaS",
    "budget": "$10,000+",
    "urgency": "high"
  }
}

Querying by Custom Fields

// Find all high-urgency SaaS contacts
const response = await fetch('https://api.goblue.app/v1/contacts/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    customFields: {
      industry: 'SaaS',
      urgency: 'high'
    }
  })
});

Tags and Segmentation

Managing Tags

Add Tags

// Add tags without removing existing ones
const contact = await getContact(contactId);
const newTags = [...(contact.tags || []), 'vip-customer', 'priority'];

await updateContact(contactId, {
  tags: [...new Set(newTags)] // Remove duplicates
});

Remove Tags

// Remove specific tags
const contact = await getContact(contactId);
const updatedTags = contact.tags.filter(tag => 
  !['old-campaign', 'outdated'].includes(tag)
);

await updateContact(contactId, { tags: updatedTags });

Replace All Tags

// Replace all tags with new set
await updateContact(contactId, {
  tags: ['new-segment', 'active-2024']
});

Common Tag Strategies

Source Tracking

google-ads, facebook, website, referral

Lead Quality

hot-lead, warm-lead, cold-lead, qualified

Campaign Tracking

campaign-q1-2024, holiday-promo, webinar-series

Behavioral

high-engagement, price-sensitive, feature-focused

Error Handling

Common Error Responses

400 Bad Request

Cause: Invalid data or format

{
  "status": "error",
  "message": "Invalid contact status",
  "errors": [
    {
      "field": "status",
      "message": "Status must be one of: new, contacted, responded, converted"
    }
  ]
}

404 Not Found

Cause: Contact doesn’t exist

{
  "status": "error",
  "message": "Contact not found",
  "code": "CONTACT_NOT_FOUND"
}

409 Conflict

Cause: Duplicate phone number

{
  "status": "error",
  "message": "Contact with this phone number already exists",
  "code": "DUPLICATE_PHONE_NUMBER",
  "existingContactId": "existing-contact-id"
}

Best Practices

Data Management

Regular Cleanup

Periodically remove inactive or unresponsive contacts

Consistent Tagging

Establish clear tagging conventions across your team

Status Updates

Keep contact statuses current for accurate reporting

Custom Fields

Use consistent naming for custom fields across forms

Performance Optimization

// Efficient bulk operations
class ContactManager {
  async processContactBatch(contacts, batchSize = 50) {
    const batches = [];
    for (let i = 0; i < contacts.length; i += batchSize) {
      batches.push(contacts.slice(i, i + batchSize));
    }
    
    const results = [];
    for (const batch of batches) {
      const batchResult = await this.updateContactsBulk(batch);
      results.push(batchResult);
      
      // Rate limiting delay
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
    
    return results;
  }
}

Next Steps

Messages API

Manage messages sent to your contacts

Forms API

Configure forms that create contacts

Contact Management Guide

Best practices for organizing contacts

Bulk Messaging

Scale your contact communication

Get Started

Core Concepts

Guides

Advanced

API Reference

​Overview

​Base URL

​Authentication

​Contact Object

​Properties

​Example Contact Object

​Endpoints

​List All Contacts

​Get Contact by ID

​Update Contact

​Delete Contact

​Get Contact Messages

​Bulk Update Contacts

​Export Contacts

​Contact Status Workflow

​Status Transitions

​Status Analytics

​Custom Fields

​Dynamic Field Handling

​Querying by Custom Fields

​Tags and Segmentation

​Managing Tags

​Common Tag Strategies

Source Tracking

Lead Quality

Campaign Tracking

Behavioral

​Error Handling

​Common Error Responses

​Best Practices

​Data Management

Regular Cleanup

Consistent Tagging

Status Updates

Custom Fields

​Performance Optimization

​Next Steps

Messages API

Forms API

Contact Management Guide

Bulk Messaging

Overview

Base URL

Authentication

Contact Object

Properties

Example Contact Object

Endpoints

List All Contacts

Get Contact by ID

Update Contact

Delete Contact

Get Contact Messages

Bulk Update Contacts

Export Contacts

Contact Status Workflow

Status Transitions

Status Analytics

Custom Fields

Dynamic Field Handling

Querying by Custom Fields

Tags and Segmentation

Managing Tags

Common Tag Strategies

Error Handling

Common Error Responses

Best Practices

Data Management

Performance Optimization

Next Steps