API Documentation

Quick Start

curl https://your-account.graycrm.io/api/v1/contacts \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Authentication & Scopes

API keys have scoped permissions. When creating an API key, select only the scopes your integration needs.

Rate Limiting

API requests are rate-limited based on your subscription plan. Rate limits reset daily at midnight UTC.

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99876
X-RateLimit-Reset: 1738281600

Pagination

List endpoints return paginated results. Use the page and per_page parameters to navigate. Default is 25 items per page.

GET /api/v1/contacts?page=2&per_page=50

{
  "data": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 10,
    "total_count": 487,
    "per_page": 50
  }
}

Idempotency

Send an Idempotency-Key header on POST requests to safely retry failed requests without creating duplicates. The key can be any unique string (UUID recommended). Responses are cached for 24 hours.

curl -X POST https://your-account.graycrm.io/api/v1/contacts \
  -H "Authorization: Bearer your_api_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"contact": {"first_name": "Jane"}}'

API Status

Check API health status. No authentication required.

{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-02-10T12:00:00Z"
}

Contacts

Manage contacts and people. Requires contacts:read or contacts:write scope.

{
  "contact": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Acme Corp",
    "source_detail": "website signup",
    "contact_emails_attributes": [
      {
        "email": "jane@example.com",
        "label": "work",
        "primary": true
      }
    ],
    "contact_phones_attributes": [
      {
        "phone": "+1-555-0100",
        "label": "mobile",
        "primary": true
      }
    ]
  }
}

Contact Emails

Manage email addresses for contacts. Requires contacts:write scope.

{
  "contact_email": {
    "email": "jane.work@example.com",
    "label": "work",
    "primary": false
  }
}

Contact Phones

Manage phone numbers for contacts. Requires contacts:write scope.

{
  "contact_phone": {
    "phone": "+1-555-0200",
    "label": "home",
    "primary": false
  }
}

Properties

Manage physical addresses and locations linked to contacts. Requires properties:read or properties:write scope.

{
  "property": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "place_id": "ChIJIQBpAG2ahYAR_6128GcTUEo",
    "source_detail": "MLS import"
  }
}

Contact-Property Links

Link contacts to properties with optional role. Requires both contacts:write and properties:write scopes.

{
  "contact_property": {
    "property_id": "550e8400-e29b-41d4-a716-446655440000",
    "role": "owner"  // owner | tenant | manager | other
  }
}

Tags

Manage tags as standalone resources. Requires tags:read or tags:write scope.

{
  "tag": {
    "name": "vip"
  }
}

Taggings

Assign and remove tags from contacts or properties. Requires tags:write scope. Note: The nested route is /taggings, not /tags.

{
  "tagging": {
    "tag_name": "vip"
  }
}

// OR

{
  "tagging": {
    "tag_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Custom Attributes

Store arbitrary key-value data on contacts or properties. Requires custom_attributes:read or custom_attributes:write scope.

{
  "custom_attribute": {
    "key": "subscription_tier",
    "value": "premium"
  }
}

Flags

Boolean flags for workflow management. Requires flags:read or flags:write scope.

{
  "flag": {
    "key": "high_value",
    "value": true
  }
}

Notes

Add notes to contacts or properties. Requires notes:read or notes:write scope.

{
  "note": {
    "body": "Called customer to discuss pricing."
  }
}

Activities

Track interactions and events. Requires activities:read or activities:write scope.

{
  "activity": {
    "activity_type": "phone_call",
    "subject": "Intro call",
    "body": "Discussed pricing and timeline.",
    "occurred_at": "2026-02-10T14:30:00Z"
  }
}

Audit Events

Complete audit trail of all changes. Requires audit_events:read scope.

Search

Full-text search across contacts and properties. Requires search:read scope.

{
  "data": {
    "contacts": [...],
    "properties": [...]
  },
  "meta": {
    "query": "john smith",
    "total_count": 15
  }
}

Batch Operations

Process up to 100 operations in a single request. Requires batch:write scope plus appropriate resource scopes.

{
  "operations": [
    {
      "method": "POST",
      "resource": "contacts",
      "body": {
        "first_name": "Jane"
      }
    },
    {
      "method": "PATCH",
      "resource": "contacts",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "body": {
        "last_name": "Doe"
      }
    },
    {
      "method": "DELETE",
      "resource": "properties",
      "id": "660e8400-e29b-41d4-a716-446655440002"
    }
  ]
}

Webhooks

Subscribe to real-time events. Manage webhooks via the web UI.

{
  "event": "contact.updated",
  "timestamp": "2026-02-10T12:00:00Z",
  "account_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "record": { ... },
    "changes": {
      "first_name": ["John", "Jane"]
    }
  }
}

App-Tag Segregation

Partition contacts and properties into per-application views using tags. Each integration can maintain its own slice of your CRM data without interfering with others.

{
  "tagging": {
    "tag_name": "app:lawn_care"
  }
}

Error Handling

All errors return a consistent JSON structure with HTTP status codes.

{
  "error": {
    "type": "validation_error",
    "message": "First name is required",
    "details": {
      "first_name": ["can't be blank"]
    }
  }
}