Grawt API Documentation

Overview

The Grawt API allows you to programmatically manage leads, tags, and custom fields in your Grawt account. This RESTful API uses JSON for request and response bodies.

Base URL: https://grawt.app/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Example:

curl -H "X-API-Key: your-api-key" https://grawt.app/api/v1/leads/fields

Error Responses

Leads

Add Lead

Creates a new lead in your account.

Endpoint: POST /api/v1/leads

Request Body:

Example Request:

{
  "email": "john@example.com",
  "fields": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  }
}

Success Response (201):

{
  "success": true,
  "message": "Lead added successfully."
}

Update Lead

Updates an existing lead by email address.

Endpoint: PUT /api/v1/leads/{email}

URL Parameters:

Request Body:

Example Request:

{
  "fields": {
    "first_name": "Jonathan",
    "phone": "+1987654321"
  }
}

Success Response (200):

{
  "success": true,
  "message": "Lead successfully updated."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Sync Lead

Creates a new lead or updates an existing one based on the email address. This is useful for upsert operations where you want to ensure the lead exists with the latest data.

Endpoint: POST /api/v1/leads/sync

Request Body:

Example Request:

{
  "email": "john@example.com",
  "fields": {
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "add_tags": [1, 5, 12],
  "remove_tags": [3]
}

Success Response (200):

{
  "success": true,
  "message": "Lead successfully created."
}

or

{
  "success": true,
  "message": "Lead successfully updated."
}

Delete Lead

Permanently deletes a lead by email address.

Endpoint: DELETE /api/v1/leads/{email}

URL Parameters:

Success Response (200):

{
  "success": true,
  "message": "Lead deleted successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Error Response (422):

{
  "success": false,
  "message": "The email ID is required and must be a valid email address."
}

Apply Tags to Lead

Applies one or more tags to an existing lead.

Endpoint: POST /api/v1/leads/{email}/tags

URL Parameters:

Request Body:

Example Request:

{
  "tags": [1, 5, 12]
}

Success Response (200):

{
  "success": true,
  "message": "Tags applied successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Remove Tags from Lead

Removes one or more tags from an existing lead.

Endpoint: DELETE /api/v1/leads/{email}/tags

URL Parameters:

Request Body:

Example Request:

{
  "tags": [3, 7]
}

Success Response (200):

{
  "success": true,
  "message": "Tags removed successfully."
}

Error Response (404):

{
  "success": false,
  "message": "Lead not found."
}

Get Lead Fields

Retrieves all available custom fields for leads in your account.

Endpoint: GET /api/v1/leads/fields

Success Response (200):

{
  "success": true,
  "user_lead_fields": [
    {
      "key": "first_name",
      "label": "First Name",
      "type": "text"
    },
    {
      "key": "last_name",
      "label": "Last Name",
      "type": "text"
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "text"
    }
  ]
}

Tags

Get Tags

Retrieves all tags in your account.

Endpoint: GET /api/v1/tags

Success Response (200):

{
  "success": true,
  "tags": [
    {
      "id": 1,
      "name": "Customer"
    },
    {
      "id": 5,
      "name": "Newsletter"
    },
    {
      "id": 12,
      "name": "VIP"
    }
  ]
}

Error Handling

All endpoints return consistent error responses.

Validation Errors (422)

When request validation fails:

{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Common Error Codes

Rate Limiting

API requests are subject to rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response.

Best Practices

Security

• Never expose your API key in client-side code (JavaScript, React, Vue, etc.)
• Store your API key in environment variables on your server
• Use server-to-server communication for API calls

Recommended Architecture

[Client Browser] → [Your Backend Server] → [Grawt API]

Your frontend should submit data to your own backend, which then makes authenticated requests to the Grawt API.

Quick Reference